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.