Facebook Docusaurus 中文文档 发布网站

此系列文章的应用示例已发布于 GitHub: docusaurus-docs-Zh_CN. 能够 Fork 帮助改进或 Star 关注更新. 欢迎 Star.

发布网站

你如今应该有一个在本地运行的网站。 一旦你将它定制为你喜欢样子，就是时候发布它了。 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/d...，因此在这种情景下咱们的项目名称将是 "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/... ，或者若是您已经设置了自定义域名。 例如，Docusaurus 的本身的 GitHub 页面 URL 是 https://docusaurus.io（它也能够经过 https://docusaurus.io/ 访问），由于它是由 https://github.com/facebook/d... GitHub repo 的 gh-pages 分支提供的。咱们强烈建议您阅读 GitHub Pages 文档 以了解更多关于这个托管解决方案的信息。

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

固然，您能够经过持续集成（CI）自动执行发布过程。

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

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

使用 Circle CI

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

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

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

1. 而后，将如下行添加到 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 文件夹中。

此系列文章的应用示例已发布于 GitHub: docusaurus-docs-Zh_CN. 能够 Fork 帮助改进或 Star 关注更新. 欢迎 Star.