侧边栏

侧边栏的工作原理

每个侧边栏都有一个对应的 YAML 文件，该文件包含在 MDN content 仓库的 files/sidebars 目录中。这定义了侧边栏链接的层次结构、每个链接应指向的 URL，以及可选的自定义标题/链接文本，这些文本可以根据需要本地化为不同的语言。

您当前正在阅读的页面有一个在 mdnsidebar.yaml 文件中定义的侧边栏。

通过在 文档源中包含 sidebar front matter 条目，侧边栏被渲染在当前页面（以及同一文档树中的所有其他页面）上。

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

All MDN pages should have sidebars.

Front matter 是连字符之间的内容。在 front matter 中包含 sidebar: mdnsidebar 会导致系统在 files/sidebars 目录中查找同名 YAML 文件。如果找到，系统会自动处理侧边栏的渲染，并将其作为一到多个有序列表（<ol> 元素）放置在页面上。

在返回此页面之前，尝试在侧边栏中导航。您会注意到，通常在导航到某个页面时，当前所在部分的链接列表将展开，而其他部分将折叠，并且您所在的页面将被高亮显示。

侧边栏 YAML 语法详解

本节将解释 MDN 侧边栏中可以包含的各种功能，以及用于生成每个侧边栏的 YAML 语法。在学习本文档时，请参考 现有侧边栏 YAML 来对照这些功能。

开始侧边栏定义

每个 YAML 侧边栏数据定义的开头是一个 sidebar 键，其值是一个定义侧边栏数据的列表。

sidebar:
  # sidebar definition goes here

单个链接

要在侧边栏中创建单个链接，请包含一个包含相对 URL 的 YAML 列表项。

sidebar:
  - /MDN/Writing_guidelines/Page_structures/Sidebars

URL 相对于 MDN URL 结构中的 docs 目录，因此，例如，/MDN/Writing_guidelines/Page_structures/Sidebars 将生成一个指向当前页面的链接。系统会自动使用链接页面的文档标题作为链接文本。如果页面在 front matter 中有一个 short-title 键，则将使用该键作为侧边栏链接的显示文本。

如果您想使用非文档 title 或 short-title 的自定义链接文本，则需要在列表项中包含两个键 — title，其中包含自定义链接文本，以及 link，其中包含之前的相对 URL。下面的示例将创建一个指向当前页面的链接，但具有自定义链接文本“Writing sidebars”。

sidebar:
  - title: Writing sidebars
    link: /MDN/Writing_guidelines/Page_structures/Sidebars

章节标题

章节标题是一个侧边栏项，其渲染字体大小比普通侧边栏项更大。这通常用作侧边栏顶部的标题，链接到该文档部分的着陆页，或者在非常大的侧边栏中用作章节分隔符（如 学习 Web 开发部分中所见）。

通过在列表项中包含一个 type 键，其值为 section，来定义一个章节标题。例如：

sidebar:
  - type: section
    link: /MDN

章节标题可以指定自定义链接文本。

sidebar:
  - type: section
    title: Yay MDN!
    link: /MDN

或者，您可以省略 link 键，仅渲染一个不包含链接的文本列表项。

sidebar:
  - type: section
    title: Yay MDN!

创建可展开/折叠的链接列表

要创建可展开/折叠的链接列表，请像以前一样创建列表项，但包含一个 children 键，其值是一个包含您希望显示为父项下子列表项的链接的列表。每个子列表项具有与父项相同的语法。子列表项甚至可以包含自己的 children，允许您创建多个层次结构级别。下面是一个示例：

sidebar:
  - title: community_guidelines
    details: closed
    children:
      - /MDN/Community
      - title: contributing_to_mdn_web_docs
        details: closed
        children:
          - /MDN/Community
          - /MDN/Community/Getting_started
      - /MDN/Community/Open_source_etiquette
      - /MDN/Community/Communication_channels
      - /MDN/Community/Discussions
# etc.

另请注意 details 键 — 此键控制列表项的子列表在页面首次加载时是渲染为关闭还是打开。可能的值如下：

• closed：子列表将渲染为关闭状态，除非当前页面被其中一个子列表链接，在这种情况下，子列表将渲染为打开状态。
• open：子列表始终渲染为打开状态。

当列表项具有 children 和 details 时，它将渲染为包含 <details>/<summary> 元素结构的内部，其中包含子列表，然后可以通过单击展开/折叠三角形小部件，或通过聚焦 summary 并按 Enter/Return 来展开/折叠。

自动渲染子页面列表

如果您想创建一个包含特定页面子页面链接的列表，可以通过指定一个 type 键值为 listSubPages，以及一个 path 键（其值是您想生成链接的页面子页面的路径）来生成此列表。例如，整个 术语表侧边栏定义（请参阅 glossarysidebar.yaml）如下所示：

sidebar:
  - type: section
    link: /Glossary
    title: Glossary
  - type: listSubPages
    path: /Glossary

这将渲染一个侧边栏，其中包含一个链接回术语表着陆页的章节标题，以及一个指向所有术语表子页面的顶层链接列表。

如果您想将此渲染为具有子页面作为可展开/折叠的子列表的父列表项，您需要另外包含一个 title 键来指定父项的显示文本，以及一个 details 键来指定 <details>/<summary> 结构的打开/关闭行为。

sidebar:
  - type: listSubPages
    path: /Glossary
    title: Glossary
    details: closed

分组子页面列表

还有一个 type 值是 listSubPagesGrouped。这会导致任何以相同子字符串后跟连字符（例如 item-）开头的子页面标题被包含在一个子列表下，该子列表的父项是该子字符串加上连字符和星号（例如 item-*）。

例如，在撰写本文时，MDN 术语表包含三个与 CORS 相关的页面：

• CORS
• CORS 安全列表请求头
• CORS-safelisted 响应头

如果我们更新术语表侧边栏定义如下：

sidebar:
  - type: listSubPagesGrouped
    path: /Glossary
    title: Glossary
    details: closed

到这些页面的链接将被分组到这样的子列表结构中：

• CORS-*
  • CORS
  • CORS 安全列表请求头
  • CORS-safelisted 响应头

在 CSS 侧边栏定义中（请参阅 cssref.yaml）可以找到更实际的示例，其中 listSubPagesGrouped 用于将相关的简写和长写属性的链接分组在一起。生成属性侧边栏菜单的列表项如下所示：

- type: listSubPagesGrouped
  path: /Web/CSS
  title: Properties
  tags:
    - css-property
    - css-shorthand-property
  details: closed

此列表项定义还包含 tags，这是下一节的主题。

过滤子页面列表

如果您在同一目录中有多种不同类型的页面（如页面 front matter 中的 page-type 键所指定），则可以通过页面类型过滤由 listSubPages 和 listSubPagesGrouped 生成的列表项。为此，请在列表项中包含一个 tags 键，其值是要包含在生成的列表项中的单个页面类型或页面类型列表。CSS 侧边栏包含几个这样的示例：

- 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
# etc.

本地化文本字符串

如上所述，您可以在 title 键中包含自定义文本来填充您的链接文本或章节标题。如果您想将该文本本地化为多种语言，您可以在 title 键中包含一个占位符，然后在此 YAML 文件底部包含一个 l10n 字典，其中定义了该占位符在不同语言中的含义。

让我们看一个示例来展示它的外观。在 HTML 侧边栏（请参阅 htmlsidebar.yaml）中，我们定义了一个列表项，用于生成指向所有 <input> 类型参考页面的链接。父列表项文本在 title 键中定义为占位符 Input_types。

- type: listSubPages
  path: /Web/HTML/Reference/Elements/input
  title: Input_types
  details: closed
  code: true

在文件底部，我们定义了 l10n 字典。l10n 中的每个键代表一种不同的区域设置 — en-US、fr、ja 等。其中每个键的值是一个子字典，其键是列表项定义中定义的占位符。每个键值是该占位符在该相应区域设置下的值。

例如

l10n:
  en-US:
    Input_types: <code>&lt;input&gt;</code> types
  fr:
    Input_types: Types <code>&lt;input&gt;</code>
  ja:
    Input_types: <code>&lt;input&gt;</code> 型
  ko:
    Input_types: <code>&lt;input&gt;</code> types
  pt-BR:
    Input_types: Tipos de <code>&lt;input&gt;</code>
  ru:
    Input_types: Типы <code>&lt;input&gt;</code>
  zh-CN:
    Input_types: <code>&lt;input&gt;</code> 类型

为了简洁起见，我们只包含了每个区域设置中 Input_types 的值。

当渲染侧边栏时，系统会将 Input_types 文本替换为其在访问的站点区域设置版本中定义的值。例如，比较以下内容：

• https://mdn.org.cn/en-US/docs/Web/HTML
• https://mdn.org.cn/en-US/docs/Web/HTML
• https://mdn.org.cn/en-US/docs/Web/HTML

如果访问的 MDN 区域设置没有为特定占位符定义值，则默认为 en-US 版本。如果未定义 en-US 版本，则显示字面占位符文本（在上述情况下为 Input_types）。

独特的侧边栏

MDN 上有一些侧边栏不使用上述标准系统。这些是更复杂的宏，需要特殊处理。

{{APIRef("<API>")}}

在 API 参考页面上显示的 API 侧边栏。对于每个接口，宏会自动生成指向接口上定义的成员的链接 — 属性、方法、事件等。单个参数是 GroupData.json 文件中定义的相应 API 组的名称。要编辑侧边栏底部显示的关联页面，请编辑该 API 的 GroupData 条目。

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

在 API 着陆页上显示的 API 侧边栏。单个参数是 GroupData.json 文件中定义的相应 API 组的名称。要编辑特定 API 侧边栏中链接的指南、接口等，请编辑该 API 的 GroupData 条目。

sidebar: jsref

通过 front matter 包含在 JavaScript 参考页面上的侧边栏。jsref 的内容在 rari 中定义，位于 jsref.rs。

如果您认为其中某个应该更新，请通过 常用渠道与我们联系。

另见

• 使用宏
• 内容链接宏
• 页面部分宏
• 横幅和通知宏