Sidebars

Every page has a sidebar. These sidebars appear because a sidebar macro has been included on the pages that create a potentially hierarchical list of links to other pages on this site.

When a sidebar macro is included, the server creates a section of content containing an unordered list of links. The links created, where they are displayed, and how they are displayed depend on the macro used and the parameters included in the markdown macro call. Some sidebars include links based on a directory's structure or page type. Others include a list of predefined pages that are hard-coded in Yari.

To include only the content generated by a sidebar macro, the macro is added immediately after the frontmatter and before the content on every page. Frontmatter is where we specify the metadata and options for each page. The frontmatter on MDN includes the page title, slug, and page type, along with other information based on the page type, such as specification URL, browser compatibility object, etc.

For example, the first lines of this document are written as:

---
title: Sidebars
slug: MDN/Writing_guidelines/Page_structures/Sidebars
page-type: mdn-writing-guide
---

{{MDNSidebar}}

The frontmatter is the content between the dashes. The sidebar macro is included immediately after the frontmatter. The {{MDNSidebar}} is a sidebar macro that adds the MDN sidebar to the page. When the sidebar is a single macro call, the macro is placed immediately after the frontmatter.

Here are a few other sidebar macros, with what they do:

{{CSSRef}}

Present on every CSS page, it generates a CSS sidebar that includes links for modules, properties, selectors, combinators, pseudo-classes, pseudo-elements, at-rules, functions, and types, with all the link lists collapsed except for the link list for the current page type.

{{DefaultAPISidebar("<API_Title>")}}

The API sidebar displayed for overview pages; the single parameter is the name of the API group in GroupData.

{{GlossarySidebar}}

Present on every glossary page, it generates the glossary sidebar that includes the list of top-level glossary terms (not the disambiguated terms) preceded by a section filter.

{{LearnSidebar}}

Present on every page within the Learn section except for common questions and how-to pages (which use the QuickLinksWithSubpages macro), it generates a sidebar based on the hard-coded links present in the Yari macro file. This macro is not based on file structure.

{{HTMLSidebar}}

Generates the sidebar for HTML documentation, including tutorials, references, and guides. The macro includes calls to the {{ ListSubpagesForSidebar}} macro for the element and attribute reference sections, while the tutorial and guide links are hard-coded.

{{HTTPSidebar}}

Generates the sidebar for HTTP documentation, including guides and reference docs.

{{PWASidebar}}

Generates the sidebar for progressive web app (PWA) documentation. The macro lists all the pages (it is not based on file structure).

The appropriate macro to use depends on the page type. The template for each page type includes the appropriate macro for that page type.

You should use existing sidebar macros, without adding any content to them. If you are creating a whole new section of content, create a macro for your sidebar in Yari.

In the unlikely event that you need to create a temporary sidebar, this section explains how that can be done. Do not submit your temporary sidebar for PR review as it will not be approved.

If you need to create a new sidebar macro, you can do so in your development environment by following these steps:

1. Remove the sidebar macro appearing immediately after the frontmatter and before the content, as each document can only have one sidebar.
2. At the end of the markdown file, add an HTML <section> element setting the id of the element to Quick_links.
3. Add a {{ListSubpagesForSidebar()}} macro with the slug of the directory for each section of content you want to include in the sidebar, along with additional markdown, between the opening and closing <section> tags.

For example, when developing the Accessibility sidebar, we could have temporarily included the following at the end of a markdown file (and removing any sidebar macro from below the frontmatter), will create a sidebar containing the links to all the ARIA role pages, preceded by a link to the ARIA roles overview page:

<section id="Quick_links">

1. [**Accessibility**](/en-US/docs/Web/Accessibility)

   {{ListSubpagesForSidebar("/en-US/docs/Web/Accessibility")}}

2. [**ARIA roles**](/en-US/docs/Web/Accessibility/ARIA/Roles)

   {{ListSubpagesForSidebar("/en-US/docs/Web/Accessibility/ARIA/Roles", "true")}}

3. [**ARIA attributes**](/en-US/docs/Web/Accessibility/ARIA/Attributes)

   {{ListSubpagesForSidebar("/en-US/docs/Web/Accessibility/ARIA/Attributes", "true")}}

</section>

If listed as the last content in the page, Yari, the engine that renders MDN, recognizes the Quick_links ID in the opening tag and converts the content of the identified <section> into a sidebar.

The {{ListSubpagesForSidebar(<parameters>)}} macro inserts the tree of subpages for the page whose slug is specified as the first parameter. The above creates a sidebar containing a link to all the Accessibility documents, followed by the ARIA roles and attributes.

Once you have determined the links to include in your sidebar, submit a pull request to Yari with your proposed sidebar macro.

The macro source code is on GitHub. Each macro includes the documentation for itself, including parameters, if any.

• Using macros
• Content link macros
• Page section macros
• Banners and notices macros
• All macros on GitHub