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 支持, 谢谢.