部署文档

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

---

GitHub Pages

如果您在GitHub上托管项目的源代码，则可以轻松使用GitHub Pages来托管项目的文档。GitHub页面有两种基本类型：Project Pages站点和User and Organization Pages站点。它们几乎完全相同但有一些重要的区别，在部署时需要不同的工作流程。

Project 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命令并在本地查看构建的文件来验证您对文档所做的任何更改。

Organization and User Pages

User and Organization 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之前，您将无法查看构建的站点。 因此，您可能希望通过使用build或serve命令并在本地查看构建的文件来验证您对文档所做的任何更改。

自定义域名

GitHub Pages支持为您的站点使用[自定义域名]。除了GitHub记录的步骤之外，您还需要执行一个额外的步骤，以便MkDocs可以与您的自定义域一起使用。您需要将“CNAME”文件添加到docs_dir的根目录中。该文件必须在一行中包含一个裸域或子域（请参阅MkDocs自己的[CNAME文件]作为示例）。您可以手动创建文件，或使用GitHub的Web界面设置自定义域（在Settings/Custom Domain下）。如果您使用Web界面，GitHub将为您创建CNAME文件并将其保存到“pages”分支的根目录。因此，下次部署时不会删除该文件，您需要将文件复制到docs_dir。将文件正确地包含在docs_dir中，MkDocs将在您构建的站点中包含该文件，并在每次运行gh-deploy命令时将其推送到“pages”分支。

如果您在使自定义域名时遇到问题，请参阅Troubleshooting custom domains的GitHub文档。

Read the Docs

Read the Docs提供免费文档托管。您可以使用任何主要版本控制系统导入文档，包括Mercurial，Git，Subversion和Bazaar。Read the Docs支持MkDocs开箱即用。 按照其网站上的[说明]正确排列存储库中的文件，创建一个帐户并将其指向您公开托管的存储库。如果配置正确，每次将提交推送到公共存储库时，文档都会更新。

其他提供商

任何可以提供静态文件的托管服务的提供商都可以用来部署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”或“上传站点(uploading site)”。

404页面

当MkDocs构建文档时，它将在构建目录中包含一个404.html文件。 部署到GitHub时，将自动使用此文件，但仅限于自定义域名。其他Web服务器可以配置使用它，但该功能并不总是可用。 有关详细信息，请参阅所选Web服务器的文档。