diff --git a/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md index ec350f09b80e092..9eedca5e2e98539 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md @@ -6,22 +6,21 @@ page-type: mdn-writing-guide {{MDNSidebar}} -All the pages MDN community members may edit include a sidebar. These sidebars are created using macros. -This article describes the different MDN sidebar macros, demonstrating how to include sidebars on MDN pages. +MDN pages all include sidebars. Most of them are created using a standard system that defines data structures in YAML files, and includes sidebars on pages using macro calls. -In this guide, you will learn how to create a sidebar of links by just including a macro and how to create sidebars with additional content. +In this guide, you will learn how these sidebars work so you can edit existing sidebars and create new ones as required. We'll also detail those that don't yet use the standard system. -## Creating 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. +> [!NOTE] +> If you're editing sidebars, you can use `yarn tool` commands for formatting and syncing with redirects. +> See [Yari's CLI Tool](https://github.com/mdn/yari/blob/main/docs/cli-tool.md) documentation for information. -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. +## How sidebars work -### Including single-macro sidebars +Each sidebar has a corresponding YAML file contained inside the MDN `content` repo's [`files/sidebars`](https://github.com/mdn/content/tree/main/files/sidebars) directory. This defines the hierarchical structure of the sidebar links, the URLs each link should point to, and optional custom heading/link text, which can be localized into different languages as required. -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. +If we take as an example the page you are currently looking at, the sidebar structure is defined in the [`mdnsidebar.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/mdnsidebar.yaml) file. -For example, the first lines of this document are written as: +The sidebar is rendered on the current page (and all others in the same document tree) by including a corresponding macro call — `\{{MDNSidebar}}` — just below the frontmatter in the [document source](https://raw.githubusercontent.com/mdn/content/refs/heads/main/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md): ```md --- @@ -33,82 +32,314 @@ 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. +The frontmatter is the content between the dashes. Including the `\{{MDNSidebar}}` macro call in the source causes the system to look for a YAML file with the same name inside the `files/sidebars` directory. If it finds one, it automatically takes care of rendering the sidebar and placing it on the page as one or more ordered lists ({{htmlelement("ol")}} elements). -Here are a few other sidebar macros, with what they do: +Try navigating around the sidebar, before returning to this page. You'll notice that generally when navigating to a page, the link list for the section you are currently in will be expanded, whereas the others will be collapsed, and the page you are on is highlighted. -- `\{{CSSRef}}` +## Standard sidebar examples - - : 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. +Some of the other standard sidebars that you will commonly encounter are as follows: -- `\{{DefaultAPISidebar("")}}` +- `\{{CSSRef}}` - - : The API sidebar displayed for overview pages; the single parameter is the name of the API group in GroupData. + - : Present on every [CSS](/en-US/docs/Web/CSS) page. - `\{{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. + - : Present on every [glossary](/en-US/docs/Glossary) page. - `\{{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](https://github.com/mdn/yari/blob/main/kumascript/macros/LearnSidebar.ejs) present in the Yari macro file. This macro is not based on file structure. + - : Present on every page within the [Learn web development section](/en-US/docs/Learn). - `\{{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](https://github.com/mdn/yari/blob/main/kumascript/macros/HTMLSidebar.ejs). + - : Generates the sidebar for [HTML](/en-US/docs/Web/HTML) documentation. - `\{{HTTPSidebar}}` - - : Generates the sidebar for [HTTP documentation](/en-US/docs/Web/HTTP), including guides and reference docs. + - : Generates the sidebar for [HTTP documentation](/en-US/docs/Web/HTTP). - `\{{PWASidebar}}` - - : Generates the sidebar for progressive web app (PWA) documentation. The macro lists all the pages (it is not based on file structure). + - : Generates the sidebar for [progressive web app (PWA)](/en-US/docs/Web/Progressive_web_apps) documentation. -The appropriate macro to use depends on the [page type](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). The [template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) for each page type includes the appropriate macro for that page type. +> [!NOTE] +> The appropriate macro to use depends on the [page type](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). The [template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) for each page type includes the appropriate macro for that page type. -### Creating new sidebars +## Sidebar YAML syntax explained -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](https://github.com/mdn/yari/tree/main/kumascript/macros) in Yari. +This section explains the different features that can be included in MDN sidebars, and the YAML syntax used to generate each one. As you work through this documentation, cross-reference the features against the [existing sidebar YAML](https://github.com/mdn/content/tree/main/files/sidebars). -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. +### Starting a sidebar definition -If you need to create a new sidebar macro, you can do so in your development environment by following these steps: +The start of each YAML sidebar data definition is a `sidebar` key, the value of which is a list defining the sidebar data: -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 {{htmlelement("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 `
` tags. +```yaml +sidebar: + # sidebar definition goes here +``` -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: +### Basic single links -```md - +```yaml +sidebar: + - type: section + link: /MDN ``` -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 `
` into a sidebar. +A section title can have custom link text specified: -The `\{{ListSubpagesForSidebar()}}` 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. +```yaml +sidebar: + - type: section + title: Yay MDN! + link: /MDN +``` -Once you have determined the links to include in your sidebar, submit a pull request to [Yari with your proposed sidebar macro](https://github.com/mdn/yari/tree/main/kumascript/macros). +Or you can omit the `link` key to just render a text list item that doesn't include a link: -> [!NOTE] -> This `
` must be appended to the end of the document, instead of between the frontmatter and the page content. Only one sidebar is created per page, so any macro listed after the frontmatter must be removed. +```yaml +sidebar: + - type: section + title: Yay MDN! +``` + +### Creating expanding/collapsing lists of links + +To create an expanding/collapsing list of links, you create a list item as before, but include a `children` key, the value of which is a list containing the links you want to show as child list items underneath the parent item. Each child list item has the same syntax as the parent. A child list item can even contain its own `children`, allowing you to create multiple hierarchy levels. Here's an example: + +```yaml +sidebar: + - title: community_guidelines + details: closed + children: + - /MDN/Community + - title: contributing_to_mdn_web_docs + details: closed + children: + - /MDN/Community/Contributing + - /MDN/Community/Contributing/Getting_started + - /MDN/Community/Contributing/Our_repositories + - /MDN/Community/Contributing/Translated_content + - /MDN/Community/Contributing/Security_vulnerability_response + - /MDN/Community/Open_source_etiquette + - /MDN/Community/Communication_channels + - /MDN/Community/Discussions + - /MDN/Community/Learn_forum + - /MDN/Community/Issues + - /MDN/Community/Pull_requests + - /MDN/Community/Roles_teams +``` + +Note also the `details` key — this controls whether a list item's list of children is rendered closed or open when the page first loads. Possible values are as follows: + +- `closed`: The children are rendered closed, unless the current page is linked to by one of the children, in which case they are rendered open. +- `open`: The children are always rendered open. + +When a list item has `children` and `details` specified, it is rendered with a {{htmlelement("details")}}/{{htmlelement("summary")}} element structure inside it, containing the child list, which can then be expanded/collapsed by clicking the disclosure triangle widget, or focusing the summary and pressing Enter/Return. + +### Automatically rendering a subpage list + +If you want to create a list containing links to a particular page's subpages, you can generate this by specifying a list item with a `type` key of value `listSubPages`, and a `path` key whose value is the path to the page whose subpages you want to generate links to. For example, the entire [Glossary](/en-US/docs/Glossary) sidebar definition (see [`glossarysidebar.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/glossarysidebar.yaml)) looks like this: + +```yaml +sidebar: + - type: section + link: /Glossary + title: Glossary + - type: listSubPages + path: /Glossary +``` + +This renders a sidebar with a section title that links back to the Glossary landing page, and a top-level list of links to all the glossary child pages. + +If you wanted to render this as a parent list item with the subpages appearing as an expanding/collapsing child list, you would need to additionally include a `title` key specifying the text to display for the parent item litem, and a `details` key specifying the open/close behavior of the `
`/`` structure. + +```yaml +sidebar: + - type: listSubPages + path: /Glossary + title: Glossary + details: closed +``` + +#### Grouping list sub-pages + +There is also a `type` value of `listSubPagesGrouped`. This causes any child pages with titles that begin with the same substring followed by a hyphen (for example `item-`) to be included in a child list under a list item of the substring, plus a hyphen and a star (for example `item-*`). + +For example, at the time of writing, the MDN Glossary contains three CORS-related pages: + +- CORS +- CORS-safelisted request header +- CORS-safelisted response header + +If we were to update the glossary sidebar definition to this: + +```yaml +sidebar: + - type: listSubPagesGrouped + path: /Glossary + title: Glossary + details: closed +``` + +The links to those pages would be grouped into a child list structure like this: + +- CORS-\* + - CORS + - CORS-safelisted request header + - CORS-safelisted response header + +More realistic examples can be found in the [CSS](/en-US/docs/Web/CSS) sidebar definition (see [`cssref.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/cssref.yaml)), where `listSubPagesGrouped` is used to group together links of related shorthand and longhand properties. The list item that generates the properties sidebar menu looks like this: + +```yaml +- type: listSubPagesGrouped + path: /Web/CSS + title: Properties + tags: + - css-property + - css-shorthand-property + details: closed +``` + +This list item definition also contains `tags`, which is the subject of the next section. + +#### Filtering list sub-pages + +If you have several different page types inside the same directory (as specified by the `page-type` key inside the page front-matter), you can filter the list items generated by `listSubPages` and `listSubPagesGrouped` by page type. To do so, include a `tags` key inside the list item, the value of which is a single page type or list of the page types you want to include in the generated list items. The CSS sidebar contains several such examples: + +```yaml +- type: listSubPages + path: /Web/CSS + title: Modules + tags: css-module + details: closed +- type: listSubPagesGrouped + path: /Web/CSS + title: Properties + tags: + - css-property + - css-shorthand-property + details: closed +- type: listSubPages + path: /Web/CSS + title: Selectors + tags: css-selector + details: closed +- type: listSubPages + path: /Web/CSS + title: Combinators + tags: css-combinator + details: closed +- type: listSubPages + path: /Web/CSS + title: Pseudo-classes + tags: css-pseudo-class + details: closed +- type: listSubPages + path: /Web/CSS + title: Pseudo-elements + tags: css-pseudo-element + details: closed +- type: listSubPages + path: /Web/CSS + title: At-rules + tags: css-at-rule + details: closed +- type: listSubPages + path: /Web/CSS + title: Functions + tags: css-function + details: closed +- type: listSubPages + path: /Web/CSS + title: Types + tags: css-type + details: closed +``` + +### Localizing text strings + +As we explained above, you can include custom text to populate your link text or section title in a `title` key. If you want to localize that text into multiple languages, you can include a placeholder in the `title` key, then include the definitions of what that placeholder should be in different languages inside a `l10n` dictionary at the bottom of the YAML file. + +Let's look at an example to show what this looks like. In the [HTML](/en-US/docs/Web/HTML) sidebar (see [`htmlsidebar.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/htmlsidebar.yaml)), we define a list item that generates a list of links to all the {{htmlelement("input")}} type reference pages. The parent list item text is defined in the `title` key as a placeholder of `Input_types`: + +```yaml +- type: listSubPages + path: /Web/HTML/Element/input + title: Input_types + details: closed + code: true +``` + +Down at the bottom of the file, we define the `l10n` dictionary. Each key inside `l10n` represents a different locale — `en-US`, `fr`, `ja`, etc. The value of each one of these keys is a sub-dictionary, the keys of which are the placeholders defined in the list item definitions. Each key value is the value of that placeholder, in that respective locale. + +For example: + +```yaml +l10n: + en-US: + Input_types: <input> types + fr: + Input_types: Types <input> + ja: + Input_types: <input> 型 + ko: + Input_types: <input> types + pt-BR: + Input_types: Tipos de <input> + ru: + Input_types: Типы <input> + zh-CN: + Input_types: <input> 类型 +``` + +We've only included the `Input_types` values in each locale for brevity. + +When the sidebar is rendered, the system replaces the `Input_types` text with its defined value in whatever locale version of the site is being accessed. Compare the following, for example: + +- https://developer.mozilla.org/en-US/docs/Web/HTML +- https://developer.mozilla.org/fr/docs/Web/HTML +- https://developer.mozilla.org/ja/docs/Web/HTML + +If an MDN locale is accessed that does not have a value defined for a particular placeholder, it defaults to the `en-US` version. If an `en-US` version is not defined, the literal placegolder text is displayed (which would be `Input_types`, in the above case). + +## Non-standard sidebars + +There are some sidebars on MDN that don't use the standard system described above. These are complex, fully automated macros that don't need changing very often: + +- `\{{APIRef("")}}` + - : The API sidebar displayed on [API reference pages](/en-US/docs/Web/API#interfaces). For each interface, the macro auto-generates links to members defined on the interface — properties, methods, events, etc. The single parameter is the name of the relevant API group defined in the [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) file. To edit the related pages shown at the bottom of the sidebar, edit that API's GroupData entry. +- `\{{DefaultAPISidebar("")}}` + - : The API sidebar displayed on [API landing pages](/en-US/docs/Web/API#specifications). The single parameter is the name of the relevant API group defined in the [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) file. To edit the guides, interfaces, etc. linked to in a particular API's sidebar, edit that API's GroupData entry. +- `\{{JSRef("")}}` + - : The sidebar on [JavaScript reference pages](/en-US/docs/Web/JavaScript/Reference). The single parameter is the directory you want to generate the links for. -The [macro source code](https://github.com/mdn/yari/tree/main/kumascript/macros) is on GitHub. Each macro includes the documentation for itself, including parameters, if any. +If you think one of these should be updated, get in touch with us via the [usual channels](/en-US/docs/MDN/Community/Communication_channels). ## See also