側邊欄

側邊欄的工作原理

每個側邊欄都有一個對應的 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.club.tw/en-US/docs/Web/HTML
• https://mdn.club.tw/en-US/docs/Web/HTML
• https://mdn.club.tw/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。

如果您認為其中某個應該更新，請透過 常用渠道與我們聯絡。

另見

• 使用宏
• 內容連結宏
• 頁面部分宏
• 橫幅和通知宏