Commonly-used macros - The MDN project 编辑

This page lists many of the general-purpose macros created for use on MDN. For how-to information on using these macros, see Using macros and Using link macros. See Other macros for information on macros that are infrequently used, are used only in special contexts, or are deprecated. There is also a complete list of all macros on MDN. 

See also the CSS style guide for styles available for your use.

Linking

Creating a single hyperlink

In general, you don't need to use macros for creating arbitrary links. Use the Link button in the Editor interface to create links. 

• The Glossary macro creates a link to a specified term's entry in the MDN glossary. This macro accepts one required and two optional parameters:

  Examples:

  1. The term's name (such as "HTML").
  2. The text to display in the article instead of the term name (this should be used rarely).Optional
  3. If this parameter is specified and is non-zero, the custom styling normally applied to glossary links is not applied.Optional
  • {{Glossary("HTML")}} yields HTML
  • {{Glossary("CSS", "Cascading Style Sheets")}} yields Cascading Style Sheets
  • {{Glossary("HTML", "", 1)}} yields HTML
• anch - creates link to in-page section:
  • {{anch("Linking to pages in references")}};

  • Demo: Linking to pages in references

Linking to pages in references

There are various macros for linking to pages in specific reference areas of MDN.

• cssxref links to a page in the CSS Reference.
  Example: {{CSSxRef("cursor")}}, results in: cursor.
• domxref links to pages in the DOM reference; if you include parentheses at the end, the template knows to display the link to look like a function name. For example, {{DOMxRef("document.getElementsByName()")}} results in document.getElementsByName() while {{DOMxRef("Node")}} results in Node.
• event links to pages in the DOM Event reference, for example: {{Event("change")}} results in change.
• HTMLElement links to an HTML element in the HTML Reference.
• htmlattrxref links to an HTML attribute, either a global attribute description if you only specify the attribute name or an attribute associated with a specific element if you specify an attribute name and an element name. For example, {{HTMLAttrxRef("lang")}}will create this link: lang. {{HTMLAttrxRef("type","input")}} will create this link: type.
• jsxref links to a page in the JavaScript Reference.
• SVGAttr links to a specific SVG attribute. For example, {{SVGAttr("d")}} creates this link: d.
• SVGElement links to an SVG element in the SVG Reference.
• HTTPHeader links to an HTTP header.
• HTTPMethod links to an HTTP request method.
• HTTPStatus links to an HTTP response status code.

Linking to bugs

• Bugs
  • bug allows you to link to a bug on bugzilla.mozilla.org easily using this syntax: {{Bug(123456)}}. This gives you: bug 123456.
  • WebkitBug inserts a link to a bug in the WebKit bug database. For example, {{WebkitBug(31277)}} inserts WebKit bug 31277.

Navigation aids for multi-page guides

Previous, Next, and PreviousNext provide navigation controls for articles which are part of sequences. For the single-way templates, the only parameter needed is the wiki location of the previous or next article in the sequence. For PreviousNext, the two parameters needed are the wiki locations of the appropriate articles. The first parameter is for the previous article and the second is for the next article.

Code samples

Live samples

• EmbedLiveSample lets you embed the output of a code sample on a page, as described in Live samples.
• LiveSampleLink creates a link to a page containing the output of a code sample on a page, as described in Live samples.

Sidebar generation

There are templates for almost every large collection of pages. They typically link back to the main page of the reference/guide/tutorial (this is often needed because our breadcrumbs sometimes can't do this) and put the article in the appropriate category.

• CSSRef generates the sidebar for CSS reference pages.
• HTMLRef generates the sidebar for HTML reference pages.
• APIRef generates the sidebar for Web API reference pages.

General-purpose formatting

Inline indicators for API documentation

optional_inline and ReadOnlyInline are used in API documentation, usually when describing the list of properties of an object or parameters of a function.

Usage: {{Optional_Inline}} or {{ReadOnlyInline}}. Example:

isCustomObjectRead only

Indicates, if true, that the object is a custom one.

parameterXOptional

Blah blah blah...

Status and compatibility indicators

Inline indicators with no additional parameters

Non-standard

non-standard_inline inserts an in-line mark indicating the API has not been standardized and is not on a standards track.

Syntax

{{Non-standard_Inline}}

Examples

• Icon:

Experimental

experimental_inline inserts an in-line mark indicating the API is not widely implemented and may change in the future.

Syntax

{{Experimental_Inline}}

Examples

• Icon:

Inline indicators that support specifying the technology

In these macros the parameter (when specified) should be one of the strings "html", "js", "css", or "gecko", followed by the version number.

Deprecated

deprecated_inline inserts an in-line deprecated mark to discourage the use of an API that is officially deprecated. Note: "Deprecated" means that the item should no longer be used, but still functions. If you mean that it no longer works at all, use the term "obsolete."

Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Syntax

{{Deprecated_Inline}} or{{Deprecated_Inline("gecko5")}}

Examples

• Icon:
• Badge:Deprecated since Gecko 5

Obsolete

obsolete_inline inserts an in-line obsolete mark to prevent the use of, for example, a function, method or property which is officially obsolete.

Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Syntax

{{Obsolete_Inline}} or {{Obsolete_Inline("js1.8.5")}}

Examples

• Icon:
• Badge:Obsolete since JavaScript 1.8.5

Template badges

These macros are mostly used on the WebAPI page. See Creating new badges for information on creating a new badge.

Page or section header indicators

These templates have the same semantics as their inline counterparts described above. The templates should be placed directly underneath the main page title (or breadcrumb navigation if available) in the reference page. They can also be used to mark up a section on a page.

• non-standard_header: {{Non-standard_Header}}

  Non-standard

  This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

• SeeCompatTable should be used on pages that document experimental features. Example: {{SeeCompatTable}}

  Experimental

  This is an experimental technology
  Check the Browser compatibility table carefully before using this in production.

• deprecated_header: {{Deprecated_Header}}

  Deprecated

  This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

• deprecated_header with parameter: {{Deprecated_Header("gecko5")}}

  Deprecated since Gecko 5 (Firefox 5 / Thunderbird 5 / SeaMonkey 2.2)

  This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).
• obsolete_header: {{Obsolete_Header}}

  Obsolete

  This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

• obsolete_header with parameter: {{Obsolete_Header("gecko30")}}

  Obsolete since Gecko 30 (Firefox 30 / Thunderbird 30 / SeaMonkey 2.27 / Firefox OS 1.4)

  This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).
• secureContext_header: {{SecureContext_Header}}

  Secure context

  This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Indicating that a feature is available in web workers

The AvailableInWorkers macro inserts a localised note box indicating that a feature is available in a Web worker context.

Note: