侧边栏

所有 MDN 社区成员可以编辑的页面都包含一个侧边栏。这些侧边栏是使用宏创建的。本文档描述了不同的 MDN 侧边栏宏，演示了如何在 MDN 页面上包含侧边栏。

在本指南中，您将学习如何通过仅包含一个宏来创建链接侧边栏，以及如何创建包含附加内容的侧边栏。

创建侧边栏

每个页面都有一个侧边栏。这些侧边栏的出现是因为在创建这些页面的页面上包含了一个侧边栏宏，该宏创建了一个可能分层的链接列表，指向本网站上的其他页面。

当包含侧边栏宏时，服务器会创建一个包含无序链接列表的内容部分。创建的链接、它们显示的位置以及显示方式取决于所使用的宏和在 Markdown 宏调用中包含的参数。一些侧边栏包含基于目录结构或页面类型的链接。其他侧边栏包含一个预定义页面的列表，这些页面在 Yari 中是硬编码的。

包含单宏侧边栏

要仅包含由侧边栏宏生成的内容，请将宏添加到每个页面的前置内容之后和内容之前。前置内容是我们指定每个页面的元数据和选项的位置。MDN 上的前置内容包括页面标题、标识符和页面类型，以及基于页面类型的其他信息，例如规范 URL、浏览器兼容性对象等。

例如，本文档的第一行代码写成

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

{{MDNSidebar}}

前置内容是短横线之间的内容。侧边栏宏包含在紧接前置内容之后。{{MDNSidebar}} 是一个侧边栏宏，它将 MDN 侧边栏添加到页面。当侧边栏是一个单独的宏调用时，该宏将放置在紧接前置内容之后。

以下是一些其他侧边栏宏，以及它们的功能

{{CSSRef}}

存在于每个 CSS 页面上，它会生成一个 CSS 侧边栏，其中包含模块、属性、选择器、组合器、伪类、伪元素、规则、函数和类型的链接，所有链接列表都处于折叠状态，除了当前页面类型的链接列表。

{{DefaultAPISidebar("")}}

用于概述页面的 API 侧边栏；单个参数是在 GroupData 中的 API 组的名称。

{{GlossarySidebar}}

存在于每个词汇表页面上，它会生成词汇表侧边栏，其中包含顶层词汇表术语列表（不是消歧义的术语），前面是一个部分筛选器。

{{LearnSidebar}}

存在于 Learn 部分中的每个页面上，除了常见问题和操作指南页面（使用 QuickLinksWithSubpages 宏），它会基于 Yari 宏文件中存在的硬编码链接 生成一个侧边栏。此宏不是基于文件结构的。

{{HTMLSidebar}}

为 HTML 文档生成侧边栏，包括教程、参考和指南。该宏包含对 {{ ListSubpagesForSidebar}} 宏的调用，用于元素和属性参考部分，而教程和指南 链接是硬编码的。

{{HTTPSidebar}}

为 HTTP 文档 生成侧边栏，包括指南和参考文档。

{{PWASidebar}}

为渐进式 Web 应用 (PWA) 文档生成侧边栏。该宏列出了所有页面（它不是基于文件结构的）。

要使用的适当宏取决于 页面类型。每个页面类型的 模板 包含该页面类型的适当宏。

创建新的侧边栏

您应该使用现有的侧边栏宏，不要向其中添加任何内容。如果您要创建一个全新的内容部分，请在 Yari 中为您的侧边栏创建一个 宏。

在您需要创建临时侧边栏的极少数情况下，本节将解释如何执行此操作。请勿提交您的临时侧边栏以进行 PR 审查，因为不会批准它。

如果您需要创建一个新的侧边栏宏，您可以在开发环境中按照以下步骤进行

  1. 删除紧接前置内容之后和内容之前出现的侧边栏宏，因为每个文档只能有一个侧边栏。
  2. 在 Markdown 文件的末尾，添加一个 HTML <section> 元素，将元素的 id 设置为 Quick_links。
  3. 在开始和结束 <section> 标记之间，添加一个 {{ListSubpagesForSidebar()}} 宏，其中包含要包含在侧边栏中的每个内容部分的目录标识符，以及其他 Markdown。

例如，在开发无障碍侧边栏时，我们可以暂时在 Markdown 文件的末尾（并删除前置内容下方的任何侧边栏宏）包含以下内容，这将创建一个侧边栏，其中包含指向所有 ARIA 角色页面的链接，前面是指向 ARIA 角色概述页面的链接

md
<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>

如果列为页面中的最后一个内容，渲染 MDN 的引擎 Yari 会识别开始标记中的 Quick_links ID，并将标识的 <section> 的内容转换为侧边栏。

{{ListSubpagesForSidebar()}} 宏会插入标识符作为第一个参数指定的页面的子页面树。上面的代码将创建一个侧边栏，其中包含指向所有无障碍文档的链接，后面是 ARIA 角色和属性。

确定要包含在侧边栏中的链接后，向 Yari 提交包含您建议的侧边栏宏的拉取请求。

注意：此 <section> 必须附加到文档末尾，而不是前置内容和页面内容之间。每个页面只创建一个侧边栏，因此必须删除前置内容后列出的任何宏。

宏源代码 位于 GitHub 上。每个宏都包含自己的文档，包括参数（如果有）。

另请参阅