Docusaurus 快速建站

最新推荐文章于 2024-05-08 13:55:47 发布

eqera

最新推荐文章于 2024-05-08 13:55:47 发布

阅读量5.6k

点赞数 4

分类专栏：杂文

杂文专栏收录该内容

10 篇文章 0 订阅

订阅专栏

一、安装指南

Docusaurus 是从全新设计的，易于安装和使用，让您的网站能够快速运行。要安装 Docusaurus，我们已经创建了一个简单的脚本，可以为您提供所有的基础架构设置：

进入你将要创建文档的 GitHub repo 目录的根目录。
yarn global add docusaurus-init 或 npm install --global docusaurus-init
docusaurus-init

除了以前存在的文件和目录，您的根目录现在将包含类似于以下的结构：

root-of-repo
├── docs-examples-from-docusaurus
│   └── doc1.md
│   └── doc2.md
│   └── doc3.md
│   └── exampledoc4.md
│   └── exampledoc5.md
└── website
│   └── blog-examples-from-docusaurus
│       └── 2016-03-11-blog-post.md
│       └── 2017-04-10-blog-post-two.md
│   └── core
│       └── Footer.js
│   └── node_modules
│   └── package.json
│   └── pages
│   └── sidebars.json
│   └── siteConfig.js
│   └── static

如果您不想全局安装 init 脚本，则可以在本地安装，然后通过 npx docusaurus-init 或通过 ./node_modules/.bin/docusaurus-init 创建的 node_modules 目录运行。运行脚本后，您可能需要删除已创建的 package.json 文件和 node_modules 目录。

二、准备网站

安装 Docusaurus 之后，您现在有一个框架可以为您特定的网站工作。通过一些更改，您可以通过在本地运行网站来验证 Docusaurus 是否已正确安装。

目录结构

如安装 Docusaurus 之后所示，初始化脚本创建了一个类似于以下内容的目录结构：

root-of-repo
├── docs-examples-from-docusaurus
│   └── doc1.md
│   └── doc2.md
│   └── doc3.md
│   └── exampledoc4.md
│   └── exampledoc5.md
└── website
│   └── blog-examples-from-docusaurus
│       └── 2016-03-11-blog-post.md
│       └── 2017-04-10-blog-post-two.md
│   └── core
│       └── Footer.js
│   └── node_modules
│   └── package.json
│   └── pages
│   └── sidebars.json
│   └── siteConfig.js
│   └── static

website/core/Footer.js 文件是一个 React 组件，充当 Docusaurus 生成的网站的页脚，应该由用户自定义。
website/blog-examples-from-docusaurus 文件夹包含用 markdown 编写的博客文章的例子。
docs-examples-from-docusaurus 文件夹包含用 markdown 编写的示例文档文件。
website/pages 文件夹包含该网站的示例顶级页面。
website/static 文件夹包含示例网站使用的静态资源。
website/siteConfig.js 文件是 Docusaurus 使用的主要配置文件。

你需要保留 website/siteConfig.js 和 website/core/Footer.js 文件，但是可以随意编辑它们。

你应该保留 website/pages 和 website/static 文件夹，但可以如你所愿的改变其内容。最低限度，你应该有一个在 website/pages 内的 en/index.js 或 en/index.html 文件和一个图像用作 website/static 内的标题图标。

website/blog-examples-from-docusaurus 和 docs-examples-from-docusaurus 文件夹包含示例博客和文档的 markdown 文件。如下文所示，当您确认示例网站正确运行时，如果您希望使用这些文件运行 Docusaurus，则需要分别将文件夹重命名为website/blog 和 docs。

验证安装

运行 Docusaurus 初始化脚本 docusaurus-init 后，会生成一个可运行的示例网站，以此为基础开发您的网站。

在根目录, 重命名 docs-examples-from-docusaurus 为 docs.
cd website
重命名 blog-examples-from-docusaurus 为 blog.
通过 yarn start 或 npm start 运行本地 web 服务器.
通过 http://localhost:3000 访问示例网站。你应该看到浏览器加载的示例网站。

三、创建网站

Docusaurus 的创造，是希望能够让你为开源项目创建一个网站和文档变得非常简单。

在安装和准备之后，为文档创建基本网站的许多工作已经完成。

网站结构

你的网站结构看起来像下面这样：

root-of-repo
├── docs
└── website
│   └── blog
│   └── core
│       └── Footer.js
│   └── node_modules
│   └── package.json
│   └── pages
│   └── sidebars.json
│   └── siteConfig.js
│   └── static

这里假设您已经删除了与初始化脚本一起安装的 .md 示例文件。

所有的文档文件都应该作为 .md 文件放在 docs 文件夹中。任何博客文章都应该在 blog 文件夹中。

博客帖子的格式必须为 yyyy-mm-dd-your-file-name.md

创建您的基本网站

要创建一个功能齐全的网站，您只需要执行几个步骤：

将您的文档以 .md 文件的形式添加到 /docs 文件夹中，并确保每个文件都有正确的header。最简单的标题如下，其中 id 是链接名称（例如 docs/intro.html），title 当然是浏览器页面的标题。
```
---
id: intro
title: 入门
---

这是我的 *新文件内容* ...
```
将零个或多个文档添加到 sidebars.json 文件，以便您的文档在侧边栏中呈现，如果您想要显示它们。

如果您不将文档添加到 sidebars.json 文件中，那么文档依然被渲染，但只能从其他文档链接到该文档，并使用已知的URL进行访问。

修改 website/siteConfig.js 文件来配置网站，按照 website/siteConfig.js 的文档指引。
创建任何的自定义页面和/或自定义 website/core/Footer.js 文件来为你的网站提供页脚。
将网站资源（如图像）放在 website/static/ 文件夹中。
运行该网站以查看更改的结果。

cd website
yarn run start # 或 `npm run start`
# 浏览 http://localhost:3000

四、发布网站

你现在应该有一个在本地运行的网站。一旦你将它定制为你喜欢样子，就是时候发布它了。 Docusaurus 生成一个静态 HTML 网站，准备好由您最喜爱的网络服务器或在线托管解决方案来提供服务。

构建静态 HTML 页面

要创建您的网站的静态版本，请在 website 的目录中运行以下脚本：

yarn run build # 或 `npm run build`

这将在 website 目录下生成 build 文件夹，其中包含 pages 中的所有文档和其他页面的 .html 文件。

托管静态 HTML 页面

此时，您可以抓取 website/build 文件夹中的所有文件，并将它们复制到您喜欢的 Web 服务器的“html”目录中。

例如，Apache 和 nginx 默认提供 /var/www/html 中的内容。也就是说，选择一个 Web 服务器或提供商是不属于 Docusaurus 的范围。

使用 GitHub 页面

虽然选择 Web 服务器或主机不在 Docusaurus 的范围内，但 Docusaurus 的设计与开放源代码项目中最受欢迎的托管解决方案之一非常吻合： GitHub Pages.

如果您已经在使用 GitHub 来托管您的项目，那么将您的 Docusaurus 站点部署到 GitHub Pages 是非常简单的。你的代码库甚至不需要公开。

即使您的 repo 是私有的，发布到 gh-pages 分支的任何内容都将是公开的。

大部分发布到 GitHub pages 的工作都是通过 publish-gh-pages 脚本自动完成的。您只需确定脚本所需的一些参数的值即可。

在 siteConfig.js 中设置两个必需的参数：

organizationName: 拥有存储库的 GitHub 用户或组织。在 Docusaurus 的情景下，这 GitHub 组织将是 "facebook"。
projectName: 您的项目的 GitHub 存储库的名称。例如，Docusaurus 托管在 https://github.com/facebook/docusaurus，所以在这种情景下我们的项目名称将是 "docusaurus"。

虽然我们建议在 siteConfig.js 中设置上面的内容，您也可以使用环境变量ORGANIZATION_NAME 和 PROJECT_NAME 。

其中一个必需的参数设置为环境变量：

GIT_USER: 具有提交访问权限的 GitHub 帐户的用户名。对于你自己的仓库，这通常是你自己的 GitHub 用户名。

还有两个可选参数设置为环境变量：

USE_SSH: 如果设置为 true，则使用 SSH 代替 HTTPS 连接到 GitHub 仓库。如果未设置此变量，则默认值是 HTTPS 。
CURRENT_BRANCH: 包含将部署的最新文档更改的分支。通常情况下，分支是 master，但是除了 gh-pages 外，它可以是任何分支（默认或其他）。如果没有设置这个变量，那么将使用当前的分支。

Docusaurus 还支持部署用户或组织站点。只需将您的项目名称设置为 "username.github.io"（其中 username 是您在 GitHub 上的用户名或组织名称），发布脚本将自动将您的站点部署到 "master" 分支的根目录。

一旦获得了参数值信息，就可以继续运行发布脚本，确保您在各种参数占位符中插入了自己的值：

要直接从命令行运行脚本，可以使用以下方法，根据需要填写参数值。

GIT_USER=<GIT_USER> \
  CURRENT_BRANCH=master \
  USE_SSH=true \
  yarn run publish-gh-pages # 或 `npm run publish-gh-pages`

指定的 GIT_USER必须具有对 organizationName 和 projectName 组合中指定的存储库的访问权限。

您现在应该可以通过访问其 GitHub Pages 的 URL 来加载您的网站，这可能是 https://username.github.io/projectName ，或者如果您已经设置了自定义域名。例如，Docusaurus 的自己的 GitHub 页面 URL 是 https://docusaurus.io（它也可以通过 https://docusaurus.io/ 访问），因为它是由 https://github.com/facebook/docusaurus GitHub repo 的 gh-pages 分支提供的。我们强烈建议您阅读 GitHub Pages 文档以了解更多关于这个托管解决方案的信息。

您可以在任何希望更新文档时运行该命令，并将更改部署到您的网站。对于文档很少更改的站点，手动运行脚本可能没问题，记住手动部署更改也不是太麻烦。

当然，您可以通过持续集成（CI）自动执行发布过程。

使用持续集成实现自动化部署

持续集成（CI）服务通常用于在新提交签入源代码控制时执行例行任务。这些任务可以是运行单元测试和集成测试的任意组合，自动构建，将包发布到 NPM，是的，将更改部署到您的网站。你所需要做的就是自动部署你的网站，只要你的文档被更新，就调用 publish-gh-pages 脚本。在下一节中，我们将介绍如何使用 Circle CI 这个流行的持续集成服务提供商。

使用 Circle CI

如果您已经为您的项目使用了 Circle CI，则只需将 Circle 配置为在发布步骤中运行 publish-gh-pages 脚本，就可以启用自动部署。

确保设置为 GIT_USER 的 GitHub 账户拥有对包含文档的 repo 的 write 访问权限，方法是在 repo 中勾选 Settings | Collaborators & teams。
以 GIT_USER 的身份登录到 GitHub。
转到 https://github.com/settings/tokens 获取 GIT_USER 并生成一个新的个人访问令牌，通过 repo 访问范围授予它完全控制私有存储库的权限。将此令牌存放在安全的地方，确保不与任何人分享。这个令牌可以用来代替你的 GitHub 密码来代表你的 GitHub 动作。
打开您的 Circle CI 仪表板，并导航到您的存储库的设置页面，然后选择 "Environment variables"。该 URL 看起来像 https://circleci.com/gh/ORG/REPO/edit#env-vars，其中 "ORG/REPO" 应该替换为您自己的 GitHub org/repo。
创建一个名为 "GITHUB_TOKEN" 的新环境变量，使用新生成的访问令牌作为值。
打开你的 circle.yml 文件，在 machine: 部分下添加以下内容，告诉 Circle 使用相对较新版本的 node 和 npm，如果可以，用 yarn 替换 npm：

machine:
  node:
    version: 6.11.2
  npm:
    version: 3.10.10

然后，将以下行添加到 deployment: 部分。如果您没有 deployment: 部分，则可以将其添加到文件末尾。

deployment:
  website:
    branch: master
    commands:
      - git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
      - git config --global user.name "<YOUR_NAME>"
      - echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
      - cd website && npm install && GIT_USER=<GIT_USER> npm run publish-gh-pages

确保 <GIT_USER> 替换为将用于发布文档的 GitHub 帐户的实际用户名。

不要将 $ GITHUB_TOKEN 的实际值放在 circle.yml 中。我们已经在步骤 3 中将其作为环境变量进行配置。

如果你想为你的 GitHub repo 连接使用 SSH，你可以设置 USE_SSH=true。所以上面的命令看起来像这样：cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages.

与手动运行 publish-gh-pages 脚本不同的是，当脚本在 Circle 环境中运行时，CURRENT_BRANCH 的值已经被定义为 CircleCI 中的一个环境变量，并且会被脚本自动获取。

现在，无论何时一个新的提交出现在 master 中，Circle CI 都会运行您的测试套件，如果一切通过，您的网站将通过 publish-gh-pages 脚本进行部署。

如果您更愿意使用部署密钥而不是个人访问令牌，则可以从 Circle CI instructions 添加 read/write 部署密钥。

提示 & 技巧

当使用 Circle CI 初始部署到 gh-pages 分支时，您可能会注意到，由于缺少测试，提交给 gh-pages 分支触发的一些作业无法成功运行。您可以通过创建具有以下内容的基本 Circle CI 配置轻松解决此问题：

# Circle CI 2.0 Config File
# 这个配置文件将阻止测试在 gh-pages 分支上运行。
version: 2
jobs:
  build:
    machine: true
    branches:
      ignore: gh-pages
    steps:
      -run: echo "Skipping tests on gh-pages branch"

将这个文件保存为 config.yml，并将其放在 website/assets 文件夹内的 .circleci 文件夹中。

五、添加博客

初始设置

要设置您的网站的博客，先在您的仓库的网站目录中创建一个 blog 文件夹。

然后，在 siteConfig.js 中添加一个 header link 到你的博客：

headerLinks: [
    ...
    {blog: true, label: 'Blog'},
    ...
]

添加博文

要在博客中发布，请在博客文件夹中创建一个格式为 YYYY-MM-DD-My-Blog-Post-Title.md 的文件。发布日期是从文件名中提取的。

例如，在 website/blog/2017-08-18-Introducing-Docusaurus.md:

---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: Introducing Docusaurus
---

博文内容..

Header 参数

唯一必需的字段是title; 不过，我们也提供了将作者信息添加到博客文章的参数。

author - 作者署名的文本标签。
authorURL - 与作者相关的网址。这可能是一个Twitter，GitHub，Facebook帐户等。
authorFBID - 用于提取个人资料图片的 Facebook ID。
title - 博客文章标题。

摘要截断

使用博客文章中的  标记来表示在查看博客发布的所有博客文章时将显示的摘要。在  之上的任何内容都将成为摘要的一部分。例如：

---
title: 截断示例
---

所有这些将成为博客文章摘要的一部分。

就到这里。

<!--truncate-->

但是从此以后的任何内容都不会是。

不是这里。

也不是这里。

RSS 订阅

Docusaurus 为您的博客文章提供了一个简单的 RSS 源。支持 RSS 和 Atom 订阅格式。这些数据会自动添加到您的网站页面的 HTML 标签中。

RSS 订阅中提供了文章的摘要，直到  结束。如果没有找到 标签，那么所有文本最多可以使用250个字符。

社交按钮

如果您希望在博客文章的底部添加 Facebook 和/或 Twitter 社交按钮，请在 siteConfig.js 中设置 facebookAppId 和/或 twitter 网站配置参数。

六、自定义页面

您可以将网页添加到您的网站，而不是作为标准文档或博客 markdown 文件的一部分。你可以通过在 website/pages 目录中添加 .js 文件来实现。这些文件是 React 组件，并调用 render() 来创建它们，由CSS类等支持。

自定义主页

开始自定义主页的最简单方法是使用运行 Docusaurus 初始化脚本时创建的示例网站。

你可以启动你的本地服务器并跳转到 http://localhost:3000 来查看示例主页的样子。从那里，编辑 website/pages/en/index.js 文件及其各个组件以使用您想要的项目的图像和文本。

添加其它自定义页面

Docusaurus 在 website/pages/en 目录中提供了一些简单的示例页面，包括 index.js，users.js 和 help.js。这些是展示如何为 Docusaurus 创建自定义页面的很好的例子。

root-of-repo
├── docs
└── website
│   └── blog
│   └── core
│       └── Footer.js
│   └── node_modules
│   └── package.json
│   └── pages
│       └── index.js
│       └── users.js
│       └── help.js
│   └── sidebars.json
│   └── siteConfig.js
│   └── static

当然，你也可以自由地写你自己的网页。强烈建议您至少有一个索引页面，而没有提供的页面是强制性的以包含在您的网站中。有关如何使用提供的组件或包括您自己的更多信息可以在这里找到。有关如何链接到页眉导航栏中的不同页面的信息可以在这里找到。

如果你想让你的页面显示在你的导航头文件中，你需要更新 siteConfig.js 来添加到 headerLinks 元素。例如 { page: "about-slash", label: "About/"}

添加静态页面

也可以使用静态 .html 文件，但默认情况下，它们不包括 Docusaurus 的页眉，页脚或样式。这些可以像其他静态资源一样添加到 static 文件夹中。或者，它们可以放在 pages 文件夹中，而不是从 React 中渲染。

如果你想使用 Docusaurus 的样式表，你可以在 ${baseUrl}css/main.css 中访问它。如果你想为这些静态页面使用单独的 css，你可以通过将它们添加到 siteConfig.js 中的 siteConfig.separateCss 字段来排除它们与 Docusaurus 的样式的关联。

自定义网站页脚

从运行 Docusaurus 初始化脚本时创建的示例 core/Footer.js 文件开始，编辑页脚以包含您网站上的任何链接或其他您希望拥有的网站。

所提供的示例有三列，左侧有一个页脚图像，Facebook 的开放源代码标识和版权在底部。如果您的项目不是 Facebook 开源项目，请删除徽标和版权。当然，您也可以随意创造页脚，让它看起来成为您想要的样子！

可能提供的链接的一些建议：Docs，API，Twitter，Discord，Facebook groups，Stack Overflow，GitHub等

您的页脚将自动应用到您网站上的所有页面，包括文档和博客文章。唯一的例外是你所包含的任何静态 html 页面。

如果你不想为你的站点添加页脚，把 core/Footer.js 的 render 函数改为返回 null。例如:

const React = require("react");

class Footer extends React.Component {
  render() {
    return null;
  }
}

module.exports = Footer;

七、启用搜索

Docusaurus 支持使用 Algolia DocSearch 进行搜索。一旦你建立了你的网站，输入你的网站信息来让 Algolia 抓取你网站的文档页面。 Algolia 会向您发送您的网站的 API 密钥和索引名称。

启用搜索栏

在 algolia 部分的 siteConfig.js 中输入您的搜索 API 密钥和索引名称，以启用您的网站搜索。

const siteConfig = {
  ...
  algolia: {
    apiKey: "my-search-only-api-key-1234",
    indexName: "my-index-name"
  },
  ...
}

额外搜索参数

您还可以在 algolia 中使用algoliaOptions字段指定额外的 Algolia 使用的搜索参数。如果您想为文档的不同版本或语言提供不同的搜索结果，这可能会很有用。任何 "VERSION" 或 "LANGUAGE" 都将被当前页面的版本或语言所取代。关于搜索选项的更多细节可以在这里找到。

const siteConfig = {
  ...
  algolia: {
    ...
    algoliaOptions: { 
      facetFilters: [ "tags:VERSION" ], 
      hitsPerPage: 5 
    }
  },
}

控制搜索栏位置

默认情况下，搜索栏将是顶部导航栏中最右边的元素。

如果您想更改默认位置，请在 siteConfig.js 的 headerLinks 字段中将 searchBar 标志添加到您想要的位置。例如，您可能需要在内部和外部链接之间的搜索栏。

const siteConfig = {
  ...
  headerLinks: [
    {...}
    {...}
    { search: true }
    {...}
    {...}
  ],
  ...
}

禁用搜索栏

要禁用搜索栏，请注释掉（推荐）或删除 siteConfig.js 文件中的 algolia 部分。

另外，如果您在 headerLinks 中自定义了搜索栏的位置，请设置 search: false。

八、导航和侧边栏

引用网站文档

如果你想在 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' },
],

九、翻译&本地化

Docusaurus允许使用 Crowdin 轻松实现翻译功能。以英文撰写的文档文件将上传到 Crowdin，由社区内的用户进行翻译。使用英文字符串编写的顶层页面可以通过在 <translate> 标签中包装要翻译的任何字符串来翻译。其他标题和标签也将被找到并正确翻译。

Docusaurus 翻译配置

要用 Docusaurus 生成用于翻译的示例文件，请使用命令行参数 translations 运行 examples 脚本：

npm run examples translations

或

yarn examples translations

这将创建以下文件：

pages/en/help-with-translations.js
languages.js
../crowdin.yaml

pages/en/help-with-translations.js 文件包含由 examples 脚本生成的相同的起始帮助页面，但现在包含了翻译标签。

languages.js 文件告诉 Docusaurus 你想为你的网站启用什么语言。默认情况下，我们希望启用英文。

crowdin.yaml 文件用于配置 crowdin 集成，并将其复制到您的 docusaurus 项目库。如果您的docusaurus 项目驻留在 /project/website 中，则 crowdin.yaml将被复制到 /project/crowdin.yaml 中。

翻译现有文档

您的文档文件不需要更改或移动来支持翻译。他们将被上传到 Crowdin 直接翻译。

在页面上启用翻译

页面允许您自定义页面或帮助页面等页面的布局和特定内容。

包含要翻译的文字的页面应放置在 website/pages/en 文件夹中。

将需要翻译的字符串封装在一个 <translate> 标签中，并在文件的顶部添加下面的 require 语句：

...
const translate = require("../../server/translate.js").translate;
...
<h2>
  <translate>This header will be translated</translate>
</h2>
...

您还可以包含一个可选的 description 属性，为翻译者提供更多关于如何翻译字符串的上下文：

<p>
  <translate desc="flower, not verb">Rose</translate>
<p>

提取字符串到翻译

必须提取本地化页面内的字符串并提供给 Crowdin。

将以下脚本添加到您的package.json文件中：

...
"scripts": {
  "write-translations": "docusaurus-write-translations"
},
...

运行脚本将生成一个 website/i18n/en.json 文件，其中包含所有将从英文翻译成其他语言的字符串。

该脚本将包括来自以下地方的文本：

文档 markdown header 中的 title 和 sidebar_label 字符串
sidebars.json 中的类别名称
在 siteConfig.js 中的 tagline
siteConfig.js 中的 header link 的 label 字符串
在 pages 内的任何 .js 文件中的 <translate> 标签中包装的字符串

如何获得翻译的字符串

Docusaurus 本身不会从一种语言翻译到另一种语言。相反，它集成了 Crowdin 来上传翻译，然后从 Crowdin 下载适当翻译的文件。

Docusaurus 如何使用字符串翻译

本节介绍 Docusaurus 中的翻译如何工作。

字符串

Docusaurus 网站有很多字符串需要本地化。但是，维持在网站中使用的字符串列表可能是很费力的。 Docusaurus 通过集中字符串来简化这一点。

例如，标题导航可以链接到“主页”或“博客”。在页面的标题和侧边栏中找到的这个和其他字符串被提取并放置到 i18n/en.json 中。当你的文件被翻译成西班牙语时，一个 i18n/es-ES.json 文件将从 Crowdin 下载。然后，当生成西班牙语页面时，Docusaurus 将从相应的本地化字符串文件中替换相应字符串的英文版本（例如，在启用西班牙语的网站“Help”中将变成“Ayuda”）。

Markdown 文件

对于文档文件本身，下载这些文件的翻译版本，然后通过适当的版面模板进行渲染。

其它页面

对于其他页面，Docusaurus 会自动将所发现的所有 <translate> 标签转换为函数调用，从相应的本地化文件 locale.json返回翻译后的字符串。

Crowdin

Crowdin是一家提供翻译服务的公司。对于开源项目，Crowdin 提供免费的字符串翻译。

在 Crowdin 上创建您的翻译项目。您可以使用[Crowdin的指南]](https://support.crowdin.com/translation-process-overview/)来了解有关翻译工作流程的更多信息。 我们建议您不要选择“英语”作为可翻译的语言，以防止创建 en-US 本地化文件，因为这会导致混淆。

您的项目需要生成一个 crowdin.yaml 文件。

你将需要安装 crowdin-cli。请参照安装说明。

下面的例子可以由 docusaurus cli 用 examples 脚本自动生成。它应该放置在项目目录的顶层，以配置如何上传/下载文件。

以下是德语，西班牙语，法语，日语，韩语，印度尼西亚语，巴西葡萄牙语，简体中文和繁体中文的各种语言的配置示例。

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: "./"
preserve_hierarchy: true

files:
  -
    source: '/docs/*.md'
    translation: '/website/translated_docs/%locale%/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

你可以在这里了解更多关于定制你的 crowdin.yaml 文件的信息。

手动同步文件

您将需要手动同步您的文件下拉和上传到 crowdin。同步过程将上传 / docs 中的任何 markdown 文件以及 website/i18n/en.json 中的可翻译字符串。（这些字符串可以通过运行 yarn write-translations 来生成。）

您可以将以下内容添加到您的 package.json 中以手动触发 crowdin。

"scripts": {
  "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml download -b master"
},

这些命令需要拥有一个环境变量，用您的 crowdin 项目 id 和 api key（CROWDIN_PROJECT_ID，CROWDIN_API_KEY）设置。你可以像上面一样内联添加它们，或者将它们永久添加到你的 .bashrc 或 .bash_profile 中。

如果在计算机上运行多个本地化的 Docusaurus 项目，则应该将环境变量的名称更改为唯一(CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY)。

使用 CircleCI 自动同步文件

您可以使用 CircleCI 网络持续集成服务自动为您的文件下拉和上传翻译。

首先，更新项目目录中的 circle.yml 文件，包括上传要翻译的英文文件的步骤，以及使用 Crowdin CLI 下载已翻译的文件。这是一个 circle.yml 文件的例子：

machine:
  node:
    version: 6.10.3
  npm:
    version: 3.10.10

test:
  override:
    - "true"

deployment:
  website:
    branch: master
    commands:
      # 配置 git 用户
      - git config --global user.email "test-site-bot@users.noreply.github.com"
      - git config --global user.name "Website Deployment Script"
      - echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
      # 安装 Docusaurus 并生成英文字符串文件
      - cd website && npm install && npm run write-translations && cd ..
      # 安装 crowdin
      - sudo apt-get install default-jre
      - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
      - sudo dpkg -i crowdin.deb
      # 翻译 上传/下载
      - crowdin --config crowdin.yaml upload sources --auto-update -b master
      - crowdin --config crowdin.yaml download -b master
      # 构建和发布网站
      - cd website && GIT_USER=test-site-bot npm run publish-gh-pages

crowdin 命令使用 examples 脚本生成的 crowdin.yaml 文件。它应该放在您的项目目录中，以配置如何上传/下载文件。

请注意，在 crowdin.yaml 文件中，CROWDIN_PROJECT_ID 和 CROWDIN_API_KEY 是Circle 中为你的 Crowdin 项目设置的环境变量。他们可以在您的 Crowdin 项目设置中找到。

现在，Circle 将帮助您在构建您的网站之前自动获取翻译。提供的 crowdin.yaml 文件会将翻译后的文件复制到 website/translated_docs/ 中，i18n/en.json 字符串文件的翻译版本将转换为 i18n/${language}.json。

如果你想在本地使用你的机器上的 Crowdin，你可以安装 Crowdin CLI 工具并运行 circle.yaml 文件中的命令。唯一的区别是你必须在 crowdin.yaml 文件中设置 project_identifier 和 api_key 值，因为你不会设置 Circle 环境变量。

版本化翻译

如果您希望为文档进行翻译和版本控制，请将以下部分添加到 crowdin.yaml 文件的末尾：

  -
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

翻译版本的文档将被复制到 website/translated_docs/${language}/${version}/。

确保在您的 Crowdin 设置的翻译部分中将 “重复字符串” 设置为“隐藏 - 所有重复将共享相同的翻译”。此设置将确保不同版本之间的相同字符串共享一个翻译。

十、版本化

您可以使用 version 脚本根据 docs 文件夹中的最新内容来剪切新的文档版本。即使 docs 文件夹中的文档发生变化，该特定的文档集也将保留并可访问。

如何创建新版本

运行以下脚本以生成并列出所有网站版本的初始版本页面：

yarn examples versions

这将创建以下文件：

pages/en/versions.js

您稍后可以编辑此文件以自定义如何显示版本。

如果脚本不存在，请将以下脚本添加到 package.json 文件中：

...
"scripts": {
  "version": "docusaurus-version"
},
...

用您希望创建的版本的命令行参数运行脚本。例如：

yarn run version 1.0.0

这将保留当前在 docs 文件夹中的所有文档，并使它们作为版本 1.0.0 的文档提供。

例如，如果您使用1.0.0作为版本号运行版本脚本，则版本1.0.0将被视为您项目的最新版本。该站点将显示标题旁标题的版本号。此版本号链接到您之前创建的版本页面。

docs 文件夹中的文档将被认为是 next 版本的一部分，并使它们可用。例如在 URL docs/next/doc1.html 处，最新版本的文档使用 url docs/doc1.html。

用 yarn run version 2.0.0 再次运行脚本将会创建一个 2.0.0 版本，使得2.0.0版本成为最新版本的文档。来自1.0.0版本的文档将使用 URL docs/1.0.0/doc1.html，而 2.0.0 将使用 docs/doc1.html。

版本化模式

您可以以任何您想要的格式创建版本号，只要与现有版本不匹配，就可以使用任何版本号创建新版本。版本排序由创建版本的顺序决定，与编号的方式无关。

存储每个版本的文件

版本化的文档被放置在 website/versioned_docs/version-${version} 中，其中 ${version} 是你提供 version 脚本的版本号。

每个版本化文档的 markdown 标题都会通过将 id frontmatter 字段重命名为 original_id，然后使用 "version-${version}-${original_id}" 作为实际的 id 字段的值来更改。

版本化的边栏被复制到 website/versioned_sidebars 中，并被命名为 version-${version}-sidebars.json。

一个 website/versions.json 文件是在您第一次剪切版本时创建的，并被 Docusaurus 用来检测存在的版本。每次添加新版本时，都会将其添加到 versions.json 文件中。

如果您希望更改以前版本的文档，则可以访问相应版本的文件。

回退功能

每次指定新版本时，只有 docs 文件夹和侧边栏文件中与最新版本文件不同的文件才会被复制。如果版本之间没有变化，Docusaurus 将使用该文件的最新版本的文件。

例如，具有原始 id doc1 的文档存在于最新版本 1.0.0 中，并且具有与 docs 文件夹中具有id doc1 的文档相同的内容。当创建一个新版本 2.0.0 时，doc1 文件不会被复制到 versioned_docs/version-2.0.0/ 中。仍然会有一个 docs/2.0.0/doc1.html 的页面，但它将使用版本为 1.0.0 的文件。

重命名现有版本

要将现有版本号重命名为其他内容，请首先确保以下脚本位于 package.json 文件中：

...
"scripts": {
  "rename-version": "docusaurus-rename-version"
},
...

使用命令行参数运行脚本，当前版本名称，然后是新版本名称。例如：

yarn run rename-version 1.0.0 1.0.1

版本化和翻译

如果你想使用版本化和翻译功能，应该设置 crowdin.yaml 文件来上传和下载来自 Crowdin 的版本化文档以进行翻译。翻译后的版本化文件将进入文件夹translated_docs/${language}/version-${version}/。有关更多信息，请查看翻译指南。

十一、CLI命令

Docusaurus提供了一组脚本来帮助您生成，运行和部署您的网站。当使用 Yarn 或 npm 时，可以用 run 命令调用这些脚本。一些常见的命令是：

yarn run start: 从本地服务器构建和运行网站
yarn run examples: 创建示例配置文件

从命令行运行

脚本可以使用 Yarn 或 npm 运行。如果您已经阅读了入门指南，您可能已经熟悉 start 命令。这个命令告诉 Docusaurus 运行生成站点并启动服务器的 docusaurus-start 脚本，通常这样调用它：

yarn run start

可以使用 npm 来调用相同的脚本：

npm run start

要运行一个特定的脚本，只需将上面例子中的 start 命令替换为与脚本相关的命令即可。

使用参数

有些命令支持可选参数。例如，要在端口 8080 上启动服务器，可以在运行 start 时指定 --port 参数：

yarn run start --port 8080

如果你使用 npm 运行 Docusaurus，你仍然可以通过在 npm run <command> 和命令参数之间插入 -- 来使用命令行参数：

npm run start -- --port 8080

配置

这些脚本是作为安装过程的一部分在 website/package.json 文件的 "scripts" 键下建立的。如果您需要重新设置，请参考安装指南。

Docusaurus 提供了一些默认映射，允许您按照 node 惯例运行命令。每次输入 docusaurus-start，你都可以输入 yarn run start 或 npm start 来达到同样的目的。

命令

参考

`docusaurus-build`

别名: build.

生成静态网站，必要时应用翻译。在部署之前用于构建网站。

也可以参考 docusaurus-start.

`docusaurus-examples [feature]`

别名: examples

如果没有指定功能，则在您的项目中设置一个最低限度配置的示例网站。这个命令更深入的内容在网站准备指南中。指定一个功能 translations 或 versions 来为该功能生成额外的示例文件。

`docusaurus-publish`

别名: publish-gh-pages

构建，然后将静态网站部署到 GitHub 页面。此命令在 Circle CI 的部署步骤中运行，因此需要定义一些环境变量：

以下通常由用户在 CircleCI 的 config.yml 文件中手动设置。

GIT_USER: 与部署提交相关联的 git 用户。
USE_SSH: 是否使用 SSH 而不是 HTTPS 连接到 GitHub 仓库。

示例

GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages

以下是在构建过程中由 CircleCI 环境设置的。

CIRCLE_BRANCH: 与触发 CI 运行的提交相关联的 git 分支。
CI_PULL_REQUEST: 如果当前的 CI 运行是由提交请求中的提交触发的，那么预计会实现。

你应该在 siteConfig.js 中分别设置为 organizationName 和 projectName。如果它们未在您的站点配置中设置，则会回退到CircleCI环境。

CIRCLE_PROJECT_USERNAME: 承载git仓库的 GitHub 用户名或组织名称，例如 "facebook"。
CIRCLE_PROJECT_REPONAME: git repo的名字，例如 "Docusaurus"。

您可以在发布指南中了解更多关于使用 CircleCI 配置自动部署的信息。

`docusaurus-rename-version <currentVersion> <newVersion>`

别名: rename-version

将文档的现有版本重命名为新的版本名称。

参考版本化指南来学习更多.

`docusaurus-start [--port <number>]`

别名: start.

该脚本将构建静态网站，必要时应用翻译，然后启动本地服务器。该网站将默认从端口 3000 提供。

`docusaurus-version <version>`

别名: version

生成文档的新版本。这将导致您的网站的新副本生成并存储在其自己的版本文件夹中。用于捕获映射到特定版本的软件的 API 文档的快照。接受任何字符串作为版本号。

参考版本化指南来学习更多.

`docusaurus-write-translations`

别名: write-translations

将需要翻译成 website/i18n/en.json 文件的字符串写入英文。脚本将遍历 website/pages/en 中的每个文件，并通过 siteConfig.js 文件和其他配置文件读取英文字符串，然后在 Crowdin 上进行翻译。请参阅翻译指南了解更多信息。

十二、Markdown功能

Markdown 头部

文档

文档使用下面的 markdown 头部字段，这两个标题字段在两边用 --- 括起来：

id：一个唯一的文件 ID。如果这个字段不存在，文档的 id 将默认为文件名（不包括扩展名）。

title：文档的标题。如果这个字段不存在，文档的 title 将默认为 id。

sidebar_label：文档边栏中显示的文本。如果该字段不存在，文档的 sidebar_label 将默认为其 title。

示例:

---
id: doc1
title: My Document
sidebar_label: Document
---

版本化的文档在被复制时将其 ID 更改为包含版本号。新的 id 是 version-${version}-${id}，其中 ${version} 是该文档的版本号， ${id} 是原始的 id。此外，版本化的文档还会获得原始文档 ID 添加成的 original_id 字段。

示例:

---
id: version-1.0.0-doc1
title: My Document
sidebar_label: Document
original_id: doc1
---

博客博文

博客博文使用以下 markdown 头部字段标记，在两边都用一行 --- 括起来：

title：这篇博文的标题。

author：这篇博文的作者。如果该字段被省略，则不会显示作者姓名。

authorURL：网站用户点击作者姓名时要链接的页面。如果这个字段被省略，作者的名字将不会链接到任何东西。

authorFBID：作者的 Facebook 标识，只用于获取作者的个人资料图片以显示博客文章。如果此字段被忽略，则不会显示作者图片的博客文章。

示例:

---
title: My First Blog Post
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---

额外功能

在使用 Markdown 编写文档时，Docusaurus 支持一些额外的功能。

链接其他文档

你可以使用相对的 URL 到其他文档文件，当它们被渲染时，它们会自动转换成相应的 html 链接。

示例:

[This links to another document](other-document.md)

这个 markdown 会自动转换成一个链接到 /docs/other-document.html （或适当的翻译/版本）的链接。

当你想浏览 GitHub 上的文档时，这可能会有所帮助，因为链接将会链接到其他文档（仍然在 GitHub 上），但是文档在呈现时会有正确的HTML链接。

链接到图像和其他资源

静态资源可以通过使用相对 URL 链接到文档相同的方式。文档和博客中使用的静态资源应该分别进入 docs/assets 和 website/blog/assets。 Markdown 将被转换成正确的链接路径，以便这些路径将适用于所有语言和版本的文档。

示例:

![alt-text](assets/doc-image.png)

生成目录

您可以创建自动生成的链接列表，这些链接可以用作 API 文档的目录。

在您的 markdown 文件中，插入一行为 <AUTOGENERATED_TABLE_OF_CONTENTS> 的文字。用代码块中的每个函数的 h3 头文件写你的文档。这些将被 Docusaurus 找到，并且这些部分的链接列表将被插入到文本 <AUTOGENERATED_TABLE_OF_CONTENTS> 中。

示例:

### `docusaurus.function(a, b)`

Text describing my function


### `docdoc(file)`

Text describing my function

将生成目录的功能：

- `docusaurus.function(a, b)`
- `docdoc(file)`

每个函数都会链接到页面中的相应部分。

语法高亮

隔离的代码块默认启用语法高亮显示。会自动检测语言，但通过指定语言，您有时可以获得更好的结果。您可以使用信息字符串，在三个开启反引号之后这样做。以下JavaScript示例...

```javascript
ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);
```

...会像语法高亮显示一样：

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

高亮显示由 Highlight.js 使用 siteConfig.js 文件中指定的主题作为 highlight 键的一部分提供：

highlight: {
  theme: 'default'
}

您可以在 Highlight.js styles目录中找到支持的主题的完整列表。

注册其他语言

尽管 Highlight.js 支持许多开箱即用的语言，但您可能需要注册其他语言支持。对于这些情况，我们通过暴露 hljs 常量作为 highlight 配置键的一部分来提供接口。这可以让你调用 registerLanguage：

highlight: {
  theme: 'default',
  hljs: function(hljs) {
    hljs.registerLanguage('galacticbasic', function(hljs) {
      // ...
    });
  }
}

十三、页面和样式

Docusaurus 支持在 website/pages 文件夹中将页面编写为 React 组件，该文件夹将与网站的其他部分共享相同的页眉，页脚和样式。

页面的 URL

website/pages 中的任何 .js 文件将使用 "pages" 之后的文件路径呈现为静态 html。 website/pages/en 中的文件也将被复制到 pages 中，并将覆盖 pages 中的任何同名文件。例如，website/pages/en/help.js 文件的页面可以在 URL ${baseUrl}en/help.js 以及 URL ${baseUrl}help.js 中找到。其中 ${baseUrl} 是在 siteConfig.js 文件中设置的 baseUrl字段。

页面请求路径

Docusaurus 提供了一些有用的 React 组件供用户编写他们自己的页面，可以在 CompLibrary 模块中找到。这个模块是在 node_modules/docusaurus 中作为 Docusaurus 的一部分提供的，所以为了访问它，在渲染为静态 html 时，pages 文件夹中的页面被临时复制到 node_modules/docusaurus 中。如示例文件所示，这意味着位于 pages/en/index.js 的用户页面使用 "../../core/CompLibrary.js" 的 require 路径导入提供的组件。

这对用户意味着如果你想使用 CompLibrary 模块，请确保 require 路径设置正确。例如，在 page/mypage.js 中的一个页面将使用一个路径 "../core/CompLibrary.js"。

如果你想在你的网站文件夹中使用你自己的组件，可以使用 process.cwd() 来引用 website 文件夹来构建 require 路径。例如，如果你添加一个组件到 website/core/mycomponent.js，你可以使用 require 路径，"process.cwd() + /core/mycomponent.js"。

提供的组件

Docusaurus 在 CompLibrary 中提供了以下组件：

`CompLibrary.MarkdownBlock`

一个 React 组件，用于解析 markdown 并呈现给 HTML。

示例:

const MarkdownBlock = CompLibrary.MarkdownBlock;

<MarkdownBlock>[Markdown syntax for a link](http://www.example.com)</MarkdownBlock>

`CompLibrary.Container`

使用 Docusaurus 样式的 React 容器组件。有可选的填充和背景颜色属性，您可以配置。

填充选择: all, bottom, left, right, top.
背景选择: dark, highlight, light.

示例:

<Container padding={["bottom", "top"]} background="light">
  ...         
</Container>

`CompLibrary.GridBlock`

一个 React 组件来组织文本和图像。

align 属性确定文本对齐。文本对齐方式默认为 left，可以设置为 center 或 right。

layout 属性确定每个 GridBlock 的列部分的数量。 layout 默认为 twoColumn，也可以设置为 threeColumn 或 fourColumn。

contents 属性是一个包含 GridBlock 每个部分内容的数组。每个内容对象可以有以下字段：

content 是从 markdown 解析的章节文本
image 显示图片的路径
imageAlign 字段用于图像对齐，相对于文本，默认为 top ，可以设置为 bottom, left, 或 right
title 是从 markdown 解析的要显示的标题
imageLink 是点击图像链接目的地的

示例:

<GridBlock
  align="center"
  contents={[
    {
      content: "Learn how to use this project",
      image: siteConfig.baseUrl + "img/learn.png",
      title: `[Learn](${siteConfig.baseUrl}docs/tutorial.html)`,
      imageLink: siteConfig.baseUrl + "docs/tutorial.html"
    },
    {
      content: "Questions gathered from the community",
      image: siteConfig.baseUrl + "img/faq.png",
      imageAlign: "top",
      title: "Frequently Asked Questions"
    },
    {
      content: "Lots of documentation is on this site",
      title: "More"
    }
  ]}
  layout="threeColumn"
/>

在生成的示例文件以及 Docusaurus 自己的网站设置 repo 中，可以找到更多关于如何使用这些组件的例子。

翻译字符串

启用翻译后，website/pages/en 内的任何页面都将被翻译为所有已启用的语言。非英文网页的网址将使用 languages.js 文件中指定的语言标记。例如。法语页面 website/pages/en/help.js 的网址可以在 ${baseUrl}fr/help.html 处找到。

在编写要翻译的页面时，可以将任何要翻译的字符串包装在 <translate> 标签中。例如

<p><translate>I like translations</translate></p>

您还可以提供一个可选的说明属性，为翻译人员提供上下文。例如

<a href="/community">
  <translate desc="footer link to page referring to community github and slack">Community</translate>
</a>

添加以下require语句：

const translate = require("../../server/translate.js").translate;

请注意，这个路径对 pages/en 里面的文件是有效的，如果文件位于不同的位置，就应该相应地进行调整，正如上面讨论的那样。

使用静态资源

静态资源应该放在 website/static 文件夹中。他们可以通过他们的路径访问，不包括 "static"。例如，如果该网站的 baseUrl 为 "/docusaurus/"，website/static/img/logo.png 中的图片可用 /docusaurus/img/logo.png。

样式

您应该使用 siteConfig 中的 colors 字段来配置您的网站的主要，辅助和代码块颜色，如这里所示。你也可以像 siteConfig 文档中描述的那样配置其他颜色。

您可以通过在 website/static 文件夹中的任何位置添加自定义样式。您在 static 文件夹中提供的任何 .css 文件将连接到 Docusaurus 提供的样式的末尾，允许您根据需要添加或覆盖 Docusaurus 默认样式。

一个简单的方法来找出你想要覆盖或添加到什么类是本地启动您的服务器，并使用您的浏览器的检查元素工具。

十四、siteConfig.js

网站配置的很大一部分是通过编辑 siteConfig.js 文件完成的。

用户展示

users 数组用于存储要在您的站点上显示的每个项目/用户的对象。目前这个字段被提供给 pages/en/index.js 和 pages/en/users.js 文件使用。每个用户对象应该有 caption，image，infoLink 和 pinned 字段。caption 是当某人悬停在该用户的 image 上时显示的文本，而 infoLink 则是点击该图片将会某人谁去哪。 pinned 字段决定它是否显示在 index页面上。

目前这个 users 数组只用于 index.js 和 users.js 示例文件。如果您不希望在 index 页面上显示用户页面或显示用户，则可以删除此部分。

siteConfig 字段

siteConfig 对象包含你的网站的大部分配置设置。

必选字段

title - 网站的标题

tagline - 网站的标语

url - 网站的 URL

baseUrl - 网站的 baseUrl

projectName - 项目名称. 这必须匹配你的 GitHub 仓库项目名称（区分大小写）。

noIndex - 布尔。如果为真，Docusaurus 会礼貌地要求爬虫和搜索引擎避免索引您的网站。这是用 header 标签完成的，所以只适用于文档和页面。不会试图隐藏静态资源。这是一个尽最大努力的要求。恶意抓取工具仍然可以继续为您的网站编制索引。

headerLinks - 将在标题导航栏中使用的链接。每个对象的 label 字段将成为链接文本，也将被翻译为每种语言。

使用示例:

headerLinks: [
  // 链接到当前 语言/版本 并且 ID 为 doc1 的文档
  { doc: "doc1", label: "Getting Started" },
  // 使用当前语言链接到 pages/en/help.js 中找到的页面，如果不存在，则使用 pages/help.js。
  { page: "help", label: "Help" },
  // 链接到 href 目的地
  { href: "https://github.com/", label: "GitHub" },
  // 由 Docusaurus (${baseUrl}blog) 生成的博客链接
  { blog: true, label: "Blog" },
  // 判断链接中的搜索栏的位置
  { search: true },
  // 判断链接中的语言下拉菜单的位置
  { languages: true }
],

headerIcon - 标题导航栏中使用的图标的 URL。

favicon - 网站 favicon 的 URL。

colors - 网站的颜色配置。

primaryColor 是用于标题导航栏和侧边栏的颜色。
secondaryColor 是用于当站点窗口很窄时（包括在移动设备上）在页眉导航栏的第二行中看到的颜色。
也可以添加自定义颜色配置。例如，如果用指定为 $myColor 的颜色添加用户样式，则将 myColor 字段添加到 colors将可以让您轻松配置此颜色。

copyright - 网站页脚和订阅内的版权字符串

可选字段

默认情况下，Docusaurus 希望您的文档位于名为 docs 的目录中。该目录与 website 目录处于同一级别（即不在 website目录内）。您可以使用此字段指定文档的自定义路径。请注意，所有文档的.md文件都必须位于平面层次结构中。不可以使用文件嵌套目录*。

customDocsPath: "docs/site"

customDocsPath: "website-docs"

useEnglishUrl - 如果你没有启用翻译（例如，通过一个 languages.js 文件），那么仍然需要一个 /docs/en/doc.html 形式的链接 en），将其设置为 true。

organizationName - 托管此项目的组织或用户的 GitHub 用户名。发布脚本使用它来确定您的 GitHub 页面网站的托管位置。

editUrl - 用于编辑文档的 URL，用法示例：editUrl + 'en/doc1.md'。如果此字段被省略，则每个文档将不会有 "Edit this Doc" 按钮。

users - 前面提到的 users 数组。

disableHeaderTitle - 可以选择禁止在标题图标旁边显示标题。排除此字段以保持标题正常，否则设置为 true。

disableTitleTagline - 禁止在主页标题中显示标语的选项。排除此字段可将页面标题保留为 Title • Tagline。设置为 true，使页面标题只是 Title。

separateCss - 其中任何 css 文件不会被处理并连接到 Docusaurus 的样式文件夹。这是为了支持静态的 html 页面，它可以与 Docusaurus 样式完全独立的分开。

footerIcon - 页脚图标的 URL。目前在 core/Footer.js 文件中使用，但是可以从该文件中删除。

translationRecruitingLink - 当启用除英文以外的语言时，语言选择的 Help Translate 选项卡的 URL。这可以包括你正在使用的翻译，但不一定都是这样。

algolia - Algolia 搜索集成信息。如果该字段被排除，搜索栏将不会出现在标题中。

gaTrackingId - Google Analytics 跟踪 ID 来跟踪页面浏览量。

facebookAppId - 如果你想在你博客文章底部的 Facebook Like/Share 按钮，提供一个Facebook应用程序ID，并且按钮将显示在所有的博客文章。

twitter - 如果你想让一个 Twitter 的社交按钮出现在你的博客文章的底部，请将其设置为 true。

highlight - 语法突出显示参数:

theme 是语法突出显示时 Highlight.js 使用的主题的名称。你可以在这里找到支持的主题列表。
version 指定要使用的特定版本的 Highlight.js。
hljs 通过将 Highlight.js 的实例传递给此处指定的函数来提供一个接口，从而允许注册语法突出显示的其他语言。
defaultLang 定义一个默认的语言。如果没有在代码块的顶部指定它，将会使用它。你可以在这里找到支持的语言列表。

markdownPlugins - 一个由 Remarkable 加载的插件数组，Docusaurus 使用的 markdown 解析器和渲染器。该插件将接收对 Remarkable 实例的引用，允许定义自定义分析和呈现规则。

wrapPagesHTML - 布尔标志来指示 /pages 中的 html 文件是否应该用网站页眉和页脚的Docusaurus 样式进行封装。这个功能是实验性的，依赖于文件是 html 片段而不是完整的页面。它插入的 html 文件的内容没有额外的处理。默认为 false。

scripts - 要加载的 JavaScript 源数组。脚本标签将被插入到 HTML 头中。

stylesheets - 要加载的 CSS 源数组。链接标签将被插入到 HTML 头中。

cname - 您的网站的 CNAME。当您的网站建立时，它会进入一个 CNAME 文件。

如果用户希望跨不同文件提供一些数据，用户也可以添加自己的自定义字段。

siteConfig.js 全字段示例

const users = [
  {
    caption: "User1",
    image: "/test-site/img/docusaurus.svg",
    infoLink: "https://www.example.com",
    pinned: true
  }
];

const siteConfig = {
  title: "Docusaurus",
  tagline: "Generate websites!",
  url: "https://docusaurus.io",
  baseUrl: "/",
// 对于 github.io 类型的 URLS，你可以将 url 和 baseUrl 结合起来：
// url: "https://reasonml.github.io",
// url: "/reason-react/",
  organizationName: "facebook",
  projectName: "docusaurus",
  noIndex: false,
  headerLinks: [
    { doc: "doc1", label: "Docs" },
    { page: "help", label: "Help" },
    { search: true },
    { blog: true }
  ],
// 对于顶部导航栏中没有标题链接 -> headerLinks: [],
  headerIcon: "img/docusaurus.svg",
  favicon: "img/favicon.png",
  colors: {
    primaryColor: "#2E8555",
    secondaryColor: "#205C3B"
  },
  editUrl: "https://github.com/facebook/docusaurus/edit/master/docs/",
  users,
  disableHeaderTitle: true,
  disableTitleTagline: true,
  separateCss: ["static/css/non-docusaurus", "static/assets/separate-css"],
  footerIcon: "img/docusaurus.svg",
  translationRecruitingLink:
    "https://crowdin.com/project/docusaurus",
  algolia: {
    apiKey:
      "0f9f28b9ab9efae89810921a351753b5",
    indexName: "github"
  },
  gaTrackingId: "U-A2352",
  highlight: {
    theme: 'default'
  },
  markdownPlugins: [
    function foo(md) {
      md.renderer.rules.fence_custom.foo = function(tokens, idx, options, env, instance) {
        return '<div class="foo">bar</div>';
      }
    }
  ],
  scripts: [ "https://docusaurus.io/slash.js" ],
  stylesheets: [ "https://docusaurus.io/style.css" ],
  facebookAppId: "1615782811974223",
  twitter: "true"
};

module.exports = siteConfig;

eqera

关注

4
点赞
踩
5

收藏

觉得还不错? 一键收藏
0
评论
Docusaurus 快速建站

一、安装指南Docusaurus 是从全新设计的，易于安装和使用，让您的网站能够快速运行。要安装 Docusaurus，我们已经创建了一个简单的脚本，可以为您提供所有的基础架构设置：进入你将要创建文档的 GitHub repo 目录的根目录。yarn global add docusaurus-init 或 npm install --global docusaurus-initdocusaur...
复制链接

扫一扫

专栏目录