部署文件

一份針對部署文件到各個不同寄存供應商的基本指南

---

GitHub Pages

如果你將專案的原始程式碼寄存在 GitHub，你可以輕鬆地使用 GitHub Pages 來寄存專案的文件。GitHub Pages 網站共有兩種類型GitHub Pages 網站：專案 Pages 網站和使用者與組織 Pages 網站。這兩種類型近乎相同，但有一些重要的差異，需要在部署時採取不同的工作流程。

專案 Pages 網站

專案 Pages 網站較為簡單，因為網站檔案會部署到專案儲存庫下的某個分支（預設為 gh-pages）。在你 checkout 保存專案原始文件的 git 儲存庫的主要工作分支（通常為 master）後，請執行下列指令

mkdocs gh-deploy

這樣就完成了！幕後，MkDocs 會建立文件，並使用 ghp-import 工具提交至 gh-pages 分支，並將 gh-pages 分支推播到 GitHub。

使用 mkdocs gh-deploy --help 以取得 gh-deploy 指令的所有可選項清單。

請注意，在你將網站推播到 GitHub 之前，將無法查看已建立好的網站。因此，你可以在使用 build 或 serve 指令並在本地檢閱已建立好的檔案之前，針對你在文件做的變更進行驗證。

組織和使用者 Pages 網站

使用者和組織 Pages 網站並未繫結到特定專案，而網站檔案會部署到名為 GitHub 帳戶名稱的專屬儲存庫中 master 分支。因此，你在本地系統中需要兩個儲存庫的工作副本。舉例而言，請考慮以下檔案結構

my-project/
    mkdocs.yml
    docs/
orgname.github.io/

在針對專案進行更新並驗證後，你需要將目錄變更為 orgname.github.io 儲存庫，並從中呼叫 mkdocs gh-deploy 指令

cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master

請注意，你必須明確指出mkdocs.yml設定檔，因為它不再位於目前的工作目錄中。你還需要通知部署指令提交到master分支。你可以用 remote_branch 設定覆寫預設值，但如果你忘記在執行部署指令前變更目錄，它將會提交到專案的master分支，而這並非你所樂見。

自訂網域

GitHub Pages 支援為你的網站使用 自訂網域。除了 GitHub 說明的步驟外，你需要採取額外的一步，這樣 MkDocs 才能與你的自訂網域搭配使用。你必須將一個CNAME檔案新增到 docs_dir 的根目錄。檔案必須在單一行包含一個純粹的網域或次網域（以 MkDocs 自己的 CNAME 檔案 為例）。你可以手動建立檔案，或使用 GitHub 的 Web 介面來設定自訂網域（在「設定」/「自訂網域」之下）。如果你使用 Web 介面，GitHub 會為你建立CNAME檔案並儲存在「pages」分支的根目錄。為防止檔案在你下次部署時被移除，你需要將檔案複製到docs_dir。當檔案正確包含在你的docs_dir中，MkDocs 會將檔案包含在你的建置網站中，並在每次你執行gh-deploy指令時推送檔案到你的「pages」分支。

如果你在讓自訂網域運作時遇到問題，請參閱 GitHub 關於 自訂網域疑難排解 的文件。

Read the Docs

Read the Docs 提供免費的文件寄存。你可以使用 Git 版本控制系統匯入文件。Read the Docs 內建支援 MkDocs。依照其網站上的 說明，適當調整儲存庫中的檔案、建立帳戶並指向你的公開寄存庫。如果設定正確，你的文件將會在你每次將提交推送至你的公開儲存庫時更新。

其他供應商

任何可以提供靜態檔案的寄存供應商都可以用來提供 MkDocs 產生的文件。儘管不可能說明如何將文件上傳到每個寄存供應商，以下準則應該可以提供一些一般性的協助。

當你建置網站時（使用mkdocs build指令），所有檔案會寫入指定給 site_dir 設定選項的目錄（預設為"site"），在你的mkdocs.yaml設定檔中。通常，你只需要將目錄中的內容複製到寄存供應商伺服器根目錄的。根據你的寄存供應商設定，你可能需要使用圖形或命令列 ftp、ssh 或 scp 客户端傳輸檔案。

例如，一組典型的命令列指令可能是像這樣

mkdocs build
scp -r ./site user@host:/path/to/server/root

當然，你需要將user替換成你在寄存供應商的使用者名稱，將host替換成適當的網域名稱。此外，你需要調整/path/to/server/root以符合主機檔案系統的設定。

瀏覽主機的文件以取得詳細資訊。你可能想搜尋他們的「ftp」或「上傳網站」文件。

本機檔案

除了將文件託管在伺服器上，你也可以直接分發檔案，這些檔案可使用 file:// 架構在瀏覽器中檢視。

請注意，由於所有現代瀏覽器的安全性設定，部分功能無法正常運作，有些甚至可能無法運作。此外，少數設定需要以非常特殊的方式進行自訂。

• site_url:

  site_url 必須設定為空白字串，指示 MkDocs 建置網站，使其可與 file:// 架構搭配運作。

  site_url: ""

• use_directory_urls:

  將 use_directory_urls 設定為 false。否則頁面之間的內部連結將無法正常運作。

  use_directory_urls: false

• 搜尋:

  你需要停用搜尋外掛程式，或使用專為 file:// 架構打造的第三方搜尋外掛程式。若要停用所有外掛程式，請將 plugins 設定設為空白清單。

  plugins: []

  如果你啟用了其他外掛程式，請確保清單中不包含 search。

在撰寫文件時，請務必遵循文件記載使用相對 URL 作為所有內部連結。請記住，每個閱讀你文件的讀者都會使用不同的裝置，而且檔案在這些裝置上的儲存位置可能不同。

如果你預期文件會在離線狀態下檢視，你可能也要小心選擇主題。很多主題為了取得支援檔案，會使用 CDN，而 CDN 需要有穩定的網路連線。你必須選擇一個主題，其中包含所有支援檔案。

當你建置網站（使用 mkdocs build 指令）時，所有檔案都會寫入指定給 site_dir 設定選項的目錄中，而該選項的預設值是 "site"（位於 mkdocs.yaml 設定檔中）。一般來說，你只需要複製該目錄的內容然後分發給讀者即可。此外，你也可以選擇使用第三方工具將 HTML 檔案轉換成其他文件格式。

404 頁面

當 MkDocs 建置文件時，它會在 建置目錄中納入一個 404.html 檔案。此檔案會在部署至 GitHub 時自動使用，但只有使用自訂網域時才會使用。其他網路伺服器可能可以設定來使用這個檔案，但這個功能並不總是可用。請參閱你所選擇伺服器的文件以取得更多資訊。