使用 mkdocs gh-deploy 命令自动部署文档

介绍

mkdocs 是用于构建静态文档网站的工具，它使用 Markdown 格式编写文档，并提供了多种主题供用户选择。其中，gh-deploy 主题支持将文档部署到 GitHub Pages 上，非常方便。

开始

首先，需要安装 mkdocs 主程序和 gh-deploy 主题。可以在命令行中使用以下命令安装：

pip install mkdocs
pip install mkdocs-material

创建文档

接下来，需要创建文档项目。在本地任意目录下执行以下命令，创建一个名为 my-docs 的文档项目：

mkdocs new my-docs

执行成功后，会在当前目录下创建一个 my-docs 目录，并包含以下文件：

my-docs/
├── docs/
│   └── index.md
├── mkdocs.yml
└── README.md

其中，src/ 目录用于存放 Markdown 格式编写的文档，mkdocs.yml 文件用于配置文档项目，README.md 文件是文档项目的介绍文档。

配置

在 mkdocs.yml 文件中可以进行文档项目的配置，例如：

site_name: My Docs
theme:
  name: 'material'
  palette:
    primary: 'green'
    accent: 'light green'
nav:
  - Home: 'index.md'
  - About: 'about.md'
  - Contact: 'contact.md'

其中，site_name 是文档站点的名称，theme 是所使用的主题名称和颜色配置，nav 中则是文档页面的导航菜单项。

构建

在完成文档项目的配置后，就可以执行以下命令来构建文档网站：

mkdocs build

执行成功后，会在当前目录下生成一个名为 site 的目录，包含所有构建好的文档页面。

部署

执行以下命令来将构建好的文档部署到 GitHub Pages 上：

mkdocs gh-deploy

该命令会将构建好的文档页面提交到 GitHub 并创建一个名为 gh-pages 的分支，以供访问。

总结

mkdocs gh-deploy 命令是将静态文档部署到 GitHub Pages 的有效工具。它可以方便地将 Markdown 格式编写的文档转换为静态站点，并快速地将其部署到 GitHub 上。