此系列文章的应用示例已发布于 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
脚本,就可以启用自动部署。
- 确保设置为
GIT_USER
的 GitHub 账户拥有对包含文档的 repo 的write
访问权限,方法是在 repo 中勾选Settings | Collaborators & teams
。 - 以
GIT_USER
的身份登录到 GitHub。 - 转到 https://github.com/settings/t... 获取
GIT_USER
并生成一个新的 个人访问令牌,通过repo
访问范围授予它完全控制私有存储库的权限。 将此令牌存放在安全的地方,确保不与任何人分享。 这个令牌可以用来代替你的 GitHub 密码来代表你的 GitHub 动作。 - 打开您的 Circle CI 仪表板,并导航到您的存储库的设置页面,然后选择 "Environment variables"。 该 URL 看起来像 https://circleci.com/gh/ORG/R...,其中 "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
文件夹中。
此系列文章的应用示例已发布于 GitHub: docusaurus-docs-Zh_CN. 可以 Fork 帮助改进或 Star 关注更新. 欢迎 Star.
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。