In contrast to the macros listed in Commonly-used macros, the macros documented in this article are used infrequently or only in specific contexts, or are deprecated.
Special contexts
These macros are used only with particular contexts, such as a specific API reference.
jsapixref
links to a page in the JSAPI Reference.XPCOMxref
links to a page in the XPCOM reference. You can specify the name of an XPCOM function, class, component, or interface (although for the latter, you should useInterface
instead). This macro will find the page and create a link to it, wherever it is in the XPCOM reference subtree.npapi
links to the Gecko Plugin API Reference.interface
can be used when linking to XPCOM interfaces.
Example:{{interface("nsIIOService")}}
results in:nsIIOService
.interface-method
can be used to link to a method of a Mozilla interface in case the target interface is documented according to the current guidelines.
Example:{{interface-method("nsIFeedResult", "registerExtensionPrefix")}}
results in:nsIFeedResult.registerExtensionPrefix()
. You can also useinterfacemethod
which does the same thing.ifmethod
andifattribute
let you create a link to a particular method or attribute (respectively) on a Mozilla interface that's been created using our standard format for interface documentation. For example,{{ifmethod("nsIAutoCompleteSearch","stopSearch")}}
shows up asnsIAutoCompleteSearch.stopSearch()
. Note that forifattribute
,id="..."
must be added explicitly in the target, since attributes do not have headings.Interwiki
makes it easy to create interwiki links. Currently it supports linking to Wikipedia and Wikimo. The first parameter is the name of the wiki ("wikipedia" or "wikimo"), and the second is the path of the article. For example,{{interwiki("wikipedia", "Firefox")}}
shows up as Firefox. This template auto-detects the page language and directs to the same language on Wikipedia, for example.RFC
creates a link to the specified RFC, given its number. The syntax is simply:{{RFC(number)}}
. For example,{{RFC(2616)}}
becomes RFC 2616.
XPCOM Interface reference summaries
Every article in the XPCOM interface reference should start with the interface summary block, which is created using IFSummary
. This creates a uniform, standard format block at the top of the page with basic information about the interface. The template accepts up to 7 parameters, but requires only the first four. The parameters are, in order:
- Path of the IDL file defining the interface
- This is used to create a link to the interface's IDL on MXR so the reader can refer to it if they wish.
- Parent interface
- This is the name of the interface upon which the interface being document is based. This will be turned into a link to that interface in the interface reference and displayed.
- scriptable/not scriptable
- A string indicating whether the interface is scriptable or not. You must use either "scriptable" or "not scriptable" (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.
- Last changed in what Gecko version
- This is a string indicating the version of Gecko in which the interface was last changed. Should be a string in standard Gecko version format, such as "1.9" or "1.9.2" or even "1.9.1.6".
- Summary Optional
- A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus template (which now calls through to this one). You should always provide this.
- Version introduced Optional
- If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline showing the availability of the interface in contrast to the history of Gecko, in graphical format.
- Version deprecated Optional
- If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.
- Version obsoleted Optional
- Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.
Examples:
{{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9", "Provides assorted network utility functions, as well as functions to parse URLs.", "1.1", "1.8.1", "1.9.2")}}
nsISupports
Last changed in Gecko 1.9 (Firefox 3){{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9", "Provides assorted network utility functions, as well as functions to parse URLs.", "1.1")}}
nsISupports
Last changed in Gecko 1.9 (Firefox 3){{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9.1")}}
nsISupports
Last changed in Gecko 1.9 (Firefox 3)If your summary is more complex and needs to include non-plaintext content, you can use IFSummaryStart
and IFSummaryEnd
to bracket your summary content.
Landing page components
We have an assortment of macros that can be used to automatically generate the contents of landing pages. Here they are.
Article lists divided by topic
We have an advanced macro that generates a menu of subpages, divided up into groups by topic area; this macro is called SubpageMenuByCategories
, and it accepts as input a JSON array of tags and section names that correspond to those tags. Given that information, it pulls all subpages of the page on which the macro was invoked and produces a list of those pages, sorted into subheadings of the specified names, with each section's contents selected by the tags found on the articles.
Sections are listed in the order in which they're specified, and within each section, articles are sorted alphabetically.
Articles with the tag "Featured" are presented in special boxes at the top of the list; you should try to avoid having more than three of these.
The JSON input looks like this, for example:
{{SubpageMenuByCategories('[{"tag": "Overview", "name": "Overviews"}, {"tag": "Guide", "name": "Guides"}, {"tag": "Example", "name": "Sample code"}]')}}
This will split up the output among the headings "Overviews" (items found with the tag "Overview", "Guides" (items with the tag "Guide"), and "Sample code" (items with the tag "Example").
Community information boxes
Each top-level landing page, and some others, should have information about how to contact community related to that topic. The CommunityBox
macro creates this for you. Its syntax:
{{CommunityBox(communityName, mailingListName, newsgroupName, ircChannelName, extraLinksString)}}
The IRC channel name and extra links string parameters are both optional.
The extra links string is a specially-formatted string for specifying the additional links that appear in the right-hand column of the box, below the IRC channel information. Its format:
heading|url|text|description||heading|url|text|description...
You may specify as many additional links as you need to (although you should try to keep this down to a scant handful, to avoid making the box unwieldy).
For example:
{{CommunityBox("UberSuperTech", "dev-ubersupertech", "dev.tech.ubersuper", "devmo", "MDN|https://developer.mozilla.org/|The MDN web site|Visit the Mozilla Developer Network||Mozilla|https://www.mozilla.org/|Mozilla's web site")}}
Join the UberSuperTech community
- IRC: #devmo (learn more)
- MDN: The MDN web site
- Mozilla: Mozilla's web site
Our style guide specifies that this box must be at the bottom of the page.
Lists of subpages
ListSubpages
generates an unordered list of links to all the immediate children of the current page; useful for automatically generating tables of contents for sets of documentation.LandingPageListSubpages
outputs a two-column definition list of all immediate subpages of the current page, with their titles as the<dt>
and their SEO summary as the<dd>
. This makes it easy to automatically generate reasonably attractive landing pages.NavListWithPrioritizedPages
generates an ordered list formatted properly for use in a zone navigation sidebar (or quicklinks). As input, you can specify zero or more page slugs that should be pulled out of the main list and instead inserted at the top of the list, in the given order. All remaining pages are placed in the list alphabetically. One level of subpages is included.APIListAlpha
builds a list of the current page's subpages, formatted as a list of API terms, divided up by first letter. There are three parameters. The first is 0 if you want to include all top-level subpages or 1 to leave out subpages with "." in their names. The second and third let you add text to display as part of the name in each link. This can be used to add "<" and ">" for element links, or to add "()" at the end of lists of method names.SubpagesWithSummaries
constructs a definition list of all the immediate children of the current page. There is no other formatting done. You can get a two-column list ready for use as a multi-column landing page usingLandingPageListSubpages
.SubpagesWithTags
constructs a two-column definition list of all subpages (down several levels) of the specified page which also have one or more of the specified tags.Syntax:
{{SubpagesWithTags(rootPage, tagList)}}
rootPage
- The path of the page whose children are to be scanned. This may be omitted or
null
to default to the current page. tagList
- A comma-delineated string listing the tags that to match against. Any pages under
rootPage
which has one or more of these tags will be included in the resulting list. For example, "build, introduction" will include in the list any pages tagged either "build" or "introduction". Pages which also have the tag "Important" get sorted to the top of the list (sorted alphabetically relative to other such tagged pages).
NeedsReviewWithTags
. This template produces a list of articles for which the specified review flag is set. You may specify zero or one review types, as well as an optional list of tags to match against, and a Boolean value indicating whether or not to look across all locales or just the user's current locale.Syntax:
{{NeedsReviewWithTags(reviewtype, tagList, allLocales)}}
reviewtype
- One of "editorial", "technical", or "kumascript". This can also be an empty string if you want all review types to be included.
tagList
Optional- If present, this is a comma-delineated string listing the tags that must match before an article will be included in the resulting list. For example, "Mobile,Non-standard" will only include articles tagged with both "Mobile" and "Non-standard". You may omit this parameter, or provide an empty string, to match all pages. Pages which also have the tag "Important" get sorted to the top of the list (kept alphabetically amongst each other).
allLocales
Optional- If present, this is an integer value; if 0, only the user's current locale is included in the list. If this has any other value, all locales are included in the output.
Quicklinks
We have some macros specifically designed to create quicklinks:
- The
MakeSimpleQuicklinks
macro creates a flat list of links in the quicklinks box. Simply give it a set of paths to destination pages as its input arguments. Each link's text is the page title, and each link has a tooltip derived from the page summary. QuickLinksWithSubpages
creates a set of quicklinks comprised of the pages below the current page (or specified page, if one is given). Up to two total levels of depth are generated.
Infrequently used
outdated
can be used to flag pages that are known to be (or might be) horribly outdated. The template is followed by an optional parameter, which can be used to provide details. For example:{{outdated("It was last updated in 1999.")}}
gives you this:Warning: The content of this article may be out of date. It was last updated in 1999.
disambig
is used on the few disambiguation pages we have. Do not use this macro on Glossary disambiguation pages; use theGlossaryDisambiguation
macro instead.block-title
can be used to create bolded text which visually serves as a title for a block in a page, does not appear in the auto-generated table of contents, and can act as a link target just as headings do. The syntax is:{{block-title(title)}}
, wheretitle
is whatever you want displayed.title
also serves as the target for links to the section you are titling.block-title
is meant for use in titling Template:sidenotes, tables, images, and code blocks, particularly in places where you'll be referring to the item more than once or in places not close to the item itself.ref
andendnote
can be used to implement footnotes to articles. The footnote "number" is created using{{ref("something")}}
, wheresomething
should be some suitably descriptive word for whatever is being mentioned in the footnote. Then, at the end of the document, insert{{endnote("something")}} Blah blah, text for first footnote
to create a numbered list for the footnotes' information.OptimizeImagesNote
macro returns text that explains that we encourage the use of image optimization software to improve page load times on MDN by making image files load as fast as possible, along with a link or links to tools we recommend for the purpose. Since image uploads are discussed in several places, this macro lets us quickly update all of the places that do so at once. By default, this macro returns HTML for a standard Note box. Specifying a non-zero parameter (such as {{OptimizeImagesNote(1)}}), you can get back just the text suitable for use in a paragraph.ReleaseChannelInfo
is used to create the standard header at the top of "Firefox X for developers" pages for a given channel; it takes four parameters: the Firefox version, the Gecko version, a string indicating an expected release date, and the name of the channel on which the release can currently be downloaded.InsertFeedLinkList
outputs a list of links from an RSS feed. Its parameters configure the output significantly:- Feed URL
- Maximum number of entries to include in the output
- The heading level to use for the name of the feed, or 0 to leave that heading out
- Class name to use when building the list; this will be applied to the
<ul>
element. - List type; this is an integer value. 0 produces a simple bullet list, while 1 outputs a header for the page title followed by a paragraph with a byline in it.
- The heading level to use for the items in the list when using list type 1.
Transclusion
Transclusion is the embedding of part or all of one page into another. Exercise caution when using this macro, to ensure that the transcluded content makes sense in the context of the page it is embedded into.
Page
lets you embed some or all of a specific page into a document. It accepts five parameters:
- The URI of the page to transclude. For example, "/en-US/docs/Project:MDN/About".
- The name of the section within the page to transclude. This can be specified either as the title string or as the ID of a block to copy over. If not specified, the entire article is transcluded. Optional
- The revision number of the page version to transclude. This feature is not currently implemented, but would allow including text from specific versions of an article. Unimplemented
- A Boolean value indicating whether or not to show the heading of the top-level section being transcluded. This is useful if you wish to specify your own heading. The default value is false, meaning the heading is not included by default. Optional
- The heading level to use as the top heading level. This adjusts the outermost first-discovered level of the transcluded content to the specified number, and all other headings correspondingly. This lets you include content that has its own headings but adjust them to match the heading level at which you're including them. If you don't specify this value, the headings are not adjusted. Unimplemented
Example without heading
{{Page("/en-US/docs/MDN/About", "About Mozilla")}}
Result:
Whether you want to learn more about who we are, how to be a part of Mozilla or just where to find us, you've come to the right place. To find out what drives us and makes us different, please visit our mission page.
Example with heading
{{Page("/en-US/docs/MDN/About", "About Mozilla", 0, 1)}}
Result:
Whether you want to learn more about who we are, how to be a part of Mozilla or just where to find us, you've come to the right place. To find out what drives us and makes us different, please visit our mission page.
Creating new badges
Icon badges
We have the ability to create attractive icon-based badges to flag compatibility issues. This is done using IconBadge
, which accepts five parameters:
- The text to display in the badge next to the icon.
- Class name for the background in the circle containing the icon. This background should include the icon to display.
- Class name for the background in the text area of the badge.
- Tooltip text. The tooltip doesn't currently draw but will eventually. Optional
For example:
{{IconBadge("Privileged", "privilegedBadge", "Only available to certified apps on Firefox OS.")}}
Results in: Privileged
Other badges
We also have badges that don't have icon bubbles. The generic template for this is SimpleBadge
, which accepts three parameters:
- Text to display in the badge.
- Name of a CSS class to use as the background for the badge.
- (Optional) Text to display in a tooltip when hovering over the badge.
Deprecated
These macros have been replace by other ways of doing the same thing, and should no longer be used. If you find them in existing articles, please replace them.
Linking
- The
anch
macro inserts a link to an anchor.{{Anch("top")}}
produces<a href="#top">top</a>
(top). Note that with this template you cannot choose a link description that is different from the anchor's name. The idea was to create a template that allows easy linking to other sections in a document. Replacement: Use the Anchor toolbar button in the Editor interface. - The
SectionOnPage
macro creates a phrase that links to both the name of a section and the article containing that section. For example,{{SectionOnPage("/en-US/docs/Mozilla/Firefox/Releases/21", "Changes for Web developers")}}
outputs the following: "Changes for Web developers" in Firefox 21 for developers. - The
manch
inserts a link to a method within the current interface; this is intended only for use in interface documentation pages.{{manch("foo")}}
produces<code><a href="current/path#foo">foo()</a></code>
(foo()
). - The
Link
macro inserts a link to the specified page on MDN, using the page's title as the visible string to click on, and the tooltip picked up from the page's SEO summary. - The
LinkItem
macro inserts a link to a specified URL, with the indicated text as the visible string to click on. The link automatically picks up as its tooltip the summary of the target page. This differs fromLink
in that you must specify the title. - The
LinkItemDL
macro inserts a link to a specified URL, with the indicated text as a<dt>
which is also the link. The<dd>
element contains the specified page's summary. funcref
creates links to global functions (usually C++) documented on top-level pages. However, such pages are no longer created at the top-level of MDN.Pref
inserts a link to the entry in the Preference reference for the specified preference.spec
inserts a link to a specification. Replacement: UseSpec2
orSpecName
instead.source
allows you to link to a Mozilla source code file without having to type a long MXR URL using this syntax:{{Source("browser/Makefile.in")}}
. This gives you:browser/Makefile.in
. The text of the link is the path provided; if you want different text, then just provide a second parameter, like so:{{Source("browser/Makefile.in", "the browser/ Makefile.in")}}
, which produces the browser/ Makefile.in. Note that the link will be to the very latest version of the file in bleeding-edge code.Source_cvs
works just likesource
, except it links to the CVS repository instead of the newer mozilla-central one.Include
inserts an #include "headername.h" reference that links to the specified file in MXR. This is used in pages that want to have a heading at the top of the page telling you how to include the appropriate header file for the interface being described. For example,{{Include("mozilla/CondVar.h")}}
results in:#include "CondVar.h"
LXRSearch
can be used to create an LXR search URL.
Boilerplate
SeeDOMInterface
inserts a blurb of text explaining that a specified interface implements a given DOM interface. Use this to create simple stub pages for Gecko interfaces that simply implement standard interfaces in the DOM. For example:{{SeeDOMInterface("nsIDOMHTMLFormElement", "HTMLFormElement")}}
looks like this: ThensIDOMHTMLFormElement
interface implements the DOMHTMLFormElement
interface. See that page for details.DocPlanHelpUs
inserts boilerplate text asking for help with an upcoming or ongoing documentation project, including offering information on how to get involved and where to find basic contribution information.
Code samples
The following macros were used prior to the implementation of the built-in live sample system in Kuma, and should be replaced by uses of EmbedLiveSample
or LiveSampleLink
.
LiveSample
lets you create a button linking to a sample file; these samples were sent to Eric Shepherd for uploading. These were used on Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.CSSLiveSample
lets you create a button linking to a sample in the CSS Reference; these samples were sent to Eric Shepherd for uploading. These were used on CSS Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.DOMLiveSample
lets you create a button linking to a sample in the DOM Reference; these samples were sent to Eric Shepherd for uploading. These were used on DOM Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.HTMLLiveSample
lets you create a button linking to a sample in the HTML Reference; these samples were sent to Eric Shepherd for uploading. These were used on HTML Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.SVGLiveSample
lets you create a button linking to a sample in the DOM Reference; these samples were sent to Eric Shepherd for uploading. These were used on SVG Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.JSFiddleLink
lets you easily create a button linking to a sample on the jsFiddle web site. These should NOT be used to replace in-line samples, or MDC-uploaded samples, but to offer access to secondary examples readers can experiment with. The template accepts one parameter, the ID tag of the jsFiddle item to link to.
Organizational
LockedPage
inserts a mark bar across the page that provides an explanation for why a page is locked. This macro is obsolete because Kuma doesn't support locking pages.jsapi_ref_header
was used to create breadcrumbs for the JSAPI referenced; this is now done by Kuma, not by a macro.
Formatting
Note
inserts a specially-formatted "note" block into the article's text. This is intended to call out an interesting or important fact. Replacement: Use theNote box
style in the Editor toolbar.warning
inserts a specially-formatted "warning" block.WarningStart
andWarningEnd
define the start and end of warning block that needst to contain other macro calls .Replacement: Use theWarning box
style in the Editor toolbar.
Version indicators
The following macros are deprecated because this information should be contained in the Browser Compatibility table of the article.
gecko_minversion_header
indicates the minimum Gecko version for a feature.Gecko
inserts the text "Gecko versionnumber" into the text, but adds a tooltip to the text that, when the user hovers over it, displays the corresponding versions of Firefox, Thunderbird, and SeaMonkey.fx_minversion_header
andfx_minversion_section
indicate the minimum Firefox version for a feature.tb_minversion_header
,tb_minversion_section
, andtb_minversion_inline
indicate the minimum Thunderbird version for a feature.js_minversion_header
andjs_minversion_inline
indicate the minimum JavaScript version for a feature.MobileOnlyHeader
inserts an "Available only for mobile Firefox" header box.MobileOnlyInline
inserts a inline indicator. These indicate the version of Gecko as of which the interface is still only available for mobile.PlatformOnlyInline
: this aims to replace the MobileOnlyInline with a more generic and therefore more useful one. The one-argument version simple states "Platform only", e.g. Firefox OS Only. The two argument version states a platform and a version number, e.g. Firefox OS 2.0 Onlydom_level
indicates the minimum DOM version for a feature.renamed_inline
inserts an in-line "renamed" mark to indicate that an API has been renamed.unimplemented_inline
inserts an in-line "unimplemented" mark to prevent the use of, for example a function, method or property which is not yet implemented. Replacement: Use the Browser Compatibility table to indicate this information.unimplemented_inline_webkit
inserts an in-line "unimplemented" mark to prevent the use of, for example, a function, method or property which is not yet implemented. Replacement: Use the Browser Compatibility table to indicate this information.gecko_callout_heading
includes a Gecko version-specific call-out box.fx_minversion_note
creates a note about a minimum version of Firefox;GeckoMinVersionNoteStart
andGeckoMinVersionNoteEnd
can be used to wrap text inside a box labeled as pertaining to a given version of Gecko and later; specify the version as the sole parameter to the "start" macro.tb_minversion_note
creates a note about a minimum version of Thunderbird.js_minversion_note
creates a note about a minimum version of JavaScript.-
h1_gecko_minversion
,h2_gecko_minversion
, andh3_gecko_minversion
let you insert headers (h1, h2, and h3) that include at the right end of the line a badge indicating the Gecko version (and corresponding app versions) that the section applies to.