How to use navigation sidebars

Draft
This page is not complete.

Navigation on MDN is frequently done using sidebars that list other articles in a series as well as related content both in the same documentation suite and in other areas of MDN. MDN's sidebars are not created automatically; to include them on the page, you need to create and use a macro of some sort. In this article, we'll review the process of both creating MDN sidebar macros and how to use them in an article.

Current MDN sidebar macros

MDN already has a number of macros for creating sidebars. Most are specific to particular sections of MDN, while others are intended to create generic sidebars for documentation areas that don't otherwise have any.

AddonSidebar
Inserts a sidebar for navigating the add-ons documentation; this is primarily content about creating browser extensions.
APIRef
Inserts a sidebar used within API interface reference pages and subpages.
CanvasSidebar
Inserts a sidebar used within the HTML/DOM Canvas documentation.
DefaultAPISidebar
Inserts a default sidebar that can be used on the API overview page of an API that doesn't have its own sidebar type.
FirefoxSidebar
Inserts a sidebar used on the documentation that's specific to Firefox.
GamesSidebar
Inserts a sidebar for navigating MDN's content about developing games using web technologies.
HTMLSidebar
Inserts the sidebar used within MDN's HTML documentation.
HTTPSidebar
Inserts a sidebar for use on pages within MDN's HTTP documentation.
JSSidebar
Inserts a sidebar for use within the JavaScript documentation.
LearnSidebar
Inserts the Learning Area sidebar.
MDNSidebar
Inserts a sidebar for navigating MDN's "meta-documentation;" that is, documentation about using and editing the MDN Web Docs site itself. You can actually see that macro in use on this page.
ServiceWorkerSidebar
Inserts a sidebar for use within documentation about Service Workers.
SpiderMonkeySidebar
Inserts a sidebar for use on pages documenting SpiderMonkey, Mozilla's JavaScript engine.
ToolsSidebar
Inserts a sidebar listing pages about Firefox developer tools.
WebAssemblySidebar
Inserts a sidebar containing links related to WebAssembly.
WebExtAPISidebar
Inserts a sidebar used to navigate the API reference documentation about browser e3dtensions (WebExtensions).
WebGLSidebar
Inserts a sidebar that provides navigation of WebGL-related content.
WebRTCSidebar
Inserts a sidebar whose contents provide navigation of WebRTC documentation on MDN.
XSLTRef
Inserts a sidebar with documentation for XSLT, EXSLT and XPath.

Using sidebars

To add a sidebar to a page, find the appropriate macro, then, on the page onto which you want to insert the sidebar, click the "Edit" button. Add to the page a <div> block whose contents are simply the call to the macro. Since you can't add a <div> using the WYSIWYYG editor, you'll need to click the "Source" button in the toolbar to switch to HTML source editing mode. Once there, you can add the macro call. Typically, sidebar macros don't require any parameters, so you can just do, for example:

<div>{{MDNSidebar}}</div>

Usually, you should do this as the first line of the document. In some documents, it's been done at the bottom instead. This works fine, but for the sake of consistency, try to place it at the top.

If there's already a <div> block with macro calls at the top of the page, such as those that create banners like {{non-standard_header}}, you can put the sidebar macro inside the same <div>, like this:

<div>{{HTTPSidebar}}{{non-standard_header}}</div>

The containing block

It's important that the sidebar macro not be in a <p> block, which is what you'll get if you don't use the source editor to insert it. That's because a sidebar macro call within <p> is likely to include text that, to the Kuma platform, looks like body content. Since the code that automatically selects page summary text (used for SEO and in MDN's automatically-generated menus listing page titles and summaries) looks for the first paragraph in the article, the result can be that a portion of text from your sidebar winds up being used as the page summary. This is never what you really want.

So be sure to use a <div> wrapper around the sidebar macro call (and any other macro used before article content, for that matter).

Creating sidebars

details coming

Talk about SidebarUtilities.

There are some macros that can be used to help build sidebars:

ListSubpagesForSidebar
Creates a tree of links structured for use in a sidebar, using the subpages of the specified page.

Document Tags and Contributors

Contributors to this page: edprince, jswisher, Teeling1, ExE-Boss, Sheppy
Last updated by: edprince,