1. MDN Web Docs
  2. Writing guidelines
  3. Page structures
  4. Using macros
  5. Commonly-used macros

Commonly-used macros

This page lists many of the general-purpose macros that MDN's build system rari provides for use on MDN. For generic how-to information on using them in MDN content, see Using macros.

Linking

MDN provides a number of link macros for easing the creation of links to glossary entries, reference pages, and other topics.

Link macros are recommended over normal Markdown links because they are succinct and translation-friendly. For example, a glossary or reference link created using a macro does not need to be translated: in other locales it will automatically link to the correct version of the file.

These macros are also covered in more detail on the Link macros page.

Linking to glossary terms

The Glossary macro creates a link to the specified term's page in MDN Glossary. This macro accepts one required parameter and one optional parameter.

  • The term is a required parameter. For example, to link to the glossary page for "HTML", the macro will be {{Glossary("HTML")}}, and this will produce the link HTML.
  • The display text is an optional parameter. For example, you can write the link in the previous example as {{Glossary("HTML", "HyperText Markup Language")}}, which will produce the link HyperText Markup Language.

Linking to reference pages

There are macros for locale-independent linking to pages in specific reference areas of MDN, including HTML, CSS, JavaScript, SVG, and HTTP.

The macros are easy to use. All you need to do is specify the name of the item to link to in the first parameter. Similar to the glossary macro, most reference macros also accept a second parameter to allow you to change the display text.

See the linked source files in the first column in the following table for details.

Macro Links to pages under Example
CSSxRef CSS reference (/Web/CSS/Reference) {{CSSxRef("cursor")}} results in cursor.
{{CSSxRef(":hover")}} results in :hover.
{{CSSxRef("@media")}} results in @media.
{{CSSxRef("pow")}} results in pow().

Check details in Using cssxref with the css reference
DOMxRef DOM reference (/Web/API) {{DOMxRef("document")}} results in Document.
{{DOMxRef("document.getElementsByName()")}} results in document.getElementsByName().
{{DOMxRef("Node")}} results in Node.
HTMLElement HTML elements reference (/Web/HTML/Reference/Elements) {{HTMLElement("select")}} results in <select>.
JSxRef JavaScript reference (/Web/JavaScript/Reference) {{JSxRef("Promise")}} results in Promise.
SVGAttr SVG attribute reference (/Web/SVG/Reference/Attribute) {{SVGAttr("d")}} results in d.
SVGElement SVG Element reference (/Web/SVG/Reference/Element) {{SVGElement("view")}} results in <view>.
HTTPHeader HTTP headers (/Web/HTTP/Reference/Headers) {{HTTPHeader("ACCEPT")}} results in ACCEPT.
HTTPMethod HTTP request methods (/Web/HTTP/Reference/Methods) {{HTTPMethod("HEAD")}} results in HEAD.
HTTPStatus HTTP response status codes (/Web/HTTP/Reference/Status) {{HTTPStatus("404")}} results in 404.

Adding navigation aids for multi-page guides

Previous, Next, and PreviousNext macros provide navigation controls for articles that are part of a sequence. For the single-way templates, the only parameter needed is the slug of the previous or next article in the sequence. The PreviousNext macro requires two parameters: the first parameter is the slug for the previous article, and the second is the slug for the next article.

Generating code samples

Live samples

Adding general-purpose formatting

Adding 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:

isCustomObject Read only

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

parameterX Optional

Indicates…

Adding status and compatibility indicators

Adding 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. For more information on the definition experimental, see the Experimental, deprecated, and obsolete documentation.

Syntax

{{Experimental_Inline}}

Examples
  • Icon:

Adding inline indicators that support specifying the technology

Deprecated

Deprecated_Inline inserts an in-line deprecated mark ( ) to discourage the use of an API that is officially deprecated (or has been removed). For more information on the definition deprecated, see the Experimental, deprecated, and obsolete documentation.

Syntax

{{Deprecated_Inline}}

Examples
  • Icon:

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 not standardized. We do not recommend using non-standard features in production, as they have limited browser support, and may change or be removed. However, they can be a suitable alternative in specific cases where no standard option exists.

  • SeeCompatTable 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.

  • SecureContext_Header. Should be used on main pages like interface pages, API overview pages, and API entry points (e.g., navigator.xyz) but usually not on subpages like method and property pages. Example: {{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 localized note box indicating that a feature is available in a worker context. You can also pass some arguments to indicate that a feature works in specified worker context.

Syntax
{{AvailableInWorkers}}
{{AvailableInWorkers("window_and_worker_except_service")}}
Examples

Note: This feature is available in Web Workers, except for Service Workers.

Note: This feature is available in Web Workers.

Linking to browser compatibility and specification

The following macros are included on all reference pages, but are also supported by all page types:

{{Compat}}

Generates a compatibility table for the feature(s) defined by browser-compat in the frontmatter.

{{Specifications}}

Includes a specification table for the feature(s) defined by spec-urls in the frontmatter, if present, or from the specification listed in browser compatibility data defined by browser-compat in the frontmatter.

See also

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content