部署你的文档

将你的文档部署到各种托管提供商的基本指南

---

GitHub Pages

如果你在 GitHub 上托管项目的源代码，你可以轻松使用 GitHub Pages 来托管项目的文档。GitHub Pages 有两种基本类型：项目页面站点和用户及组织页面站点。它们几乎相同，但在部署时有一些重要的区别。

项目页面

项目页面站点更简单，因为站点文件会被部署到项目仓库中的一个分支（默认是 gh-pages）。在你 checkout 主工作分支（通常是 master）后，运行以下命令：

mkdocs gh-deploy

就是这样！在幕后，MkDocs 会构建你的文档，并使用 ghp-import 工具将它们提交到 gh-pages 分支，并将 gh-pages 分支推送到 GitHub。

使用 mkdocs gh-deploy --help 获取 gh-deploy 命令的完整选项列表。

请注意，你将无法在推送到 GitHub 之前预览构建的站点。因此，你可能希望在使用 build 或 serve 命令并在本地审查构建的文件后，再验证对文档所做的任何更改。

警告： 如果你使用 gh-deploy 命令，切勿手动编辑页面仓库中的文件，因为下次运行该命令时，你的工作将会丢失。

警告： 如果在运行 mkdocs gh-deploy 的本地仓库中有未跟踪的文件或未提交的工作，这些文件将被包含在部署的页面中。

组织和用户页面

用户和组织页面站点不与特定项目绑定，站点文件被部署到以 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 能够与你的自定义域名一起工作。你需要在 docs_dir 的根目录中添加一个 CNAME 文件。该文件必须包含一行单个裸域名或子域名（参见 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。按照他们网站上的 [说明] 正确安排仓库中的文件，创建账户并将其指向你公开托管的仓库。如果配置正确，每次你推送提交到仓库时，你的文档都会更新。 public repository.

其他提供商

任何能够提供静态文件服务的托管提供商都可以用来托管由 MkDocs 生成的文档。虽然不可能详细说明如何将文档上传到每一个托管提供商，但以下指南应能提供一些一般性的帮助。

当你构建你的站点（使用 mkdocs build 命令）时，所有文件都会被写入到 mkdocs.yaml 配置文件中分配给 site_dir 配置选项的目录（默认为 "site"）。通常，你只需要将该目录的内容复制到托管提供商服务器的根目录。根据你的托管提供商的设置，你可能需要使用图形界面或命令行的 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

• search:

  你需要禁用搜索插件，或者使用专门设计用于 file:// 方案的第三方搜索插件。要禁用所有插件，请将 plugins 设置为空列表。

  plugins: []

  如果你启用了其他插件，只需确保列表中不包含 search。

在编写文档时，务必确保所有内部链接使用相对 URL，如文档所述。请记住，每个阅读你文档的人都将使用不同的设备，文件在该设备上的位置可能也不同。

如果你预计你的文档会被离线查看，你还需要注意选择主题。许多主题使用 CDN 来获取各种支持文件，这需要实时互联网连接。你需要选择一个主题，该主题直接在主题中包含所有支持文件。

当你构建你的站点（使用 mkdocs build 命令）时，所有文件都会被写入到 mkdocs.yaml 配置文件中分配给 site_dir 配置选项的目录（默认为 "site"）。通常，你只需要复制该目录的内容并分发给你的读者。或者，你可以选择使用第三方工具将 HTML 文件转换为其他文档格式。

404 页面

当 MkDocs 构建文档时，它会在 build directory 中包含一个 404.html 文件。该文件在部署到 GitHub 时会自动使用，但仅限于自定义域名。其他 Web 服务器可能需要配置才能使用它，但该功能并不总是可用。请参阅你选择的服务器的文档以获取更多信息。