Facebook Docusaurus 中文文檔 導航和側邊欄

此係列文章的應用示例已發佈於 GitHub: docusaurus-docs-Zh_CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

導航和側邊欄

引用網站文檔

若是你想在 docs 文件夾中引用另外一個文檔（或者你經過可選 customDocsPath路徑站點配置選項設置的位置），那麼你只須要使用你想引用的文檔名稱。

例如，若是你在 doc2.md 中，而你想引用 doc1.md：

這裏引用了一個 [文檔](doc1.md).

Docusaurus 目前不支持嵌套文件夾中的文件; 只能是在一個平面文件結構中。 咱們正在考慮添加對嵌套文件夾的支持。

文檔如何連接

docs 中的新 markdown 文件將在網站上顯示爲頁面。 這些文檔的連接首先經過在每一個文檔的頭部使用 id 來建立。 若是沒有 id 字段，那麼文件的名稱將做爲連接名稱。

例如，建立諸如 "docs/getting-started.md" 之類的空文件將使新頁面 URL 成爲 /docs/getting-started.html。

假設您將其添加到您的文檔中：

---
id: intro
title: 入門
---

這是文檔的 *新內容*...

若是您在文件的標記標題中設置了 id 字段，那麼文檔將從 /docs/intro.html 形式的 URL 訪問。

您須要一個 id 字段才能將文檔添加到側邊欄。

添加文檔到側邊欄

不少時候，您將須要添加一個文檔到側邊欄，這個側邊欄將與網站頂部導航欄中的一個標題相關聯。 最多見的補充工具欄，以及在 Docusaurus 初始化時安裝的工具欄是 docs 工具欄。

"docs" 只是一個名字。 它沒有繼承的意義。 你能夠隨意更改。

您能夠在 website/sidebars.json 文件中配置側邊欄的內容以及文檔的順序。

在將文檔添加到 website/sidebars.json 以前，只能經過直接的URL訪問它們。 該文檔不會顯示在任何側邊欄。

在 sidebars.json 中，將在文檔頭中使用的 id 添加到現有的側邊欄/類別中。 在下面的狀況下，docs 是側邊欄的名稱，Getting Started 是側邊欄中的一個類別。

{
  "docs": {
    "Getting Started": [
      "getting-started"

或者你能夠在側邊欄中建立一個新的類別：

{
  "docs": {
    ...
    "My New Sidebar Category": [
      "getting-started"
    ],
    ...

添加新側邊欄

您也能夠將文檔放在新的側邊欄中。 在下面的例子中，咱們在 sidebars.json 裏面建立一個名爲 My Example Category 的類別爲 examples-sidebar 的工具欄，裏面包含一個 id 爲 my-examples 的文檔。

{
  "examples-sidebar": {
    "My Example Category": [
      "my-examples"
    ],
  },
  ...

重要的是要注意，直到你從 "example-sidebar" 側邊欄添加一個文檔到導航欄，它將會被隱藏。

添加到網站導航欄

要展開側邊欄，您須要將可點擊的標籤添加到網站頂部的網站導航欄中。 您能夠添加文檔，頁面和外部連接。

添加文檔

經過將其添加到 sidebars.json，爲該網站建立一個新的側邊欄後，您能夠經過編輯 siteConfig.js 的 headerLinks 字段來從頂部導航欄中展開新的側邊欄。

headerLinks: [
  ...
  { doc: 'my-examples', label: 'Examples' },
  ...
],

一個名爲 Examples 的標籤將被添加到網站導航欄中，當您在網站頂部點擊它時，將會顯示 examples-sidebar，默認文檔將是 my-examples。

添加自定義頁面

要將自定義頁面添加到網站導航欄，可將條目添加到 siteConfig.js 的 headerLinks 中。 例如，若是咱們在 website/pages/help.js 中有一個頁面，咱們能夠經過添加如下內容來連接到它：

headerLinks: [
  ...
  { page: 'help', label: 'Help' },
  ...
],

一個名爲 Help 的標籤將被添加到站點導航欄中，當您在站點頂部點擊它時，將顯示 help.js 頁面的內容。

添加外部連接

自定義連接能夠經過 siteConfig.js 中的如下條目添加到網站導航欄中：

headerLinks: [
  ...
  { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
  ...
],

一個名爲 GitHub 的標籤將被添加到站點導航欄中，當您在站點頂部點擊它時，外部連接的內容將被顯示。

要在新選項卡中打開外部連接，請在標題連接配置中提供一個 external: true 標誌。

網站導航欄定位

在網站頂部的網站導航欄中顯示搜索和語言下拉列表元素時，您的控制權限有限。

搜索

若是在您的網站上啓用搜索，您的搜索欄將顯示在您的連接的右側。 若是您想要在搜索欄中的連接之間添加一個搜索條目，在 headerLinks 配置數組中：

headerLinks: [
  { doc: 'foo', label: 'Foo' },
  { search: true },
  { doc: 'bar', label: 'Bar' },
],

語言下拉菜單

若是在您的網站上啓用了翻譯，則語言下拉菜單將顯示在您的連接的右側（若是啓用搜索，則會顯示在搜索欄的左側）。 若是要將語言選擇放在標題中的連接之間，請在 headerLinks 配置數組中添加一個語言條目：

headerLinks: [
  { doc: 'foo', label: 'Foo' },
  { languages: true },
  { doc: 'bar', label: 'Bar' },
],

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 謝謝.