使用 Mkdocs 在 Github 上快速部署文章#

统计信息：字数 2581 阅读6分钟

2021-11-03

为项目编写文档，找到了一款叫 MkDocs 的工具。

MkDocs 架构简单，工具可以自动创建一个配置文件 mkdocs.yml，以及 docs 文件夹，通过简单的配置，在 docs 文件夹上添加 markdown 文件作为页面。完成后工具自带部署到 Github 上的功能，通过简单的设置，就可以轻松使用 GitPage 展示项目文档。 具体细节可以参考 MkDocs 官网文档：

MkDocs 中文官网

MkDocs 英文官网

MkDocs 安装#

使用 pip 安装 mkdocs。

pip install mkdocs

安装完成后，可以检查以下 MkDocs 是否能正确安装

mkdocs --version
>> mkdocs, version 1.2.2 
# 2021年11月 1.2.2 版本

能看到版本号正常显示，即表示 MkDocs 工具以被正常安装完成。

创建文档项目#

MkDocs 提供了 mkdocs new <project name> 命令创建文档项目。然而，在一般情况下，我们都是先在 GitHub 上创建了一个已有的项目，然后再为其添加相应的文档。这里有两个方法可以参考：

• 使用 mkdocs new <project> 来创建一个新文档项目，然后将其中的 docs 文件夹以及 mkdocs.yml 配置文件复制到项目根目录下。
• 直接创建一个 mkdocs.yml 和 docs 文件夹与项目根目录下。 接下来，我们可以在 docs 目录下创建一个 index.md 文件，然后向其中添加一些内容，尝试运行一下看看文档项目是否能正常运行，具体方法如下：

mkdocs serve

等待工具运行，然后默认地址是 http://127.0.0.1:8000 我们通过浏览器打开，查看页面是否能正常显示。

超链接#

mkdocs 的链接非常简单，直接使用 MarkDown 语法的连接即可，连接路径使用项目相对路径即可。 如果是图片，可以在 docs 文件夹向创建一个 images 的文件夹，引用的使用可以使用方法:

![image](./images/image.jpg)

部署到 Github#

MkDocs 部署到 Github 也非常简单，使用命令 mkdocs gh-deploy ，工具就会自动将相应内容推送到项目的 gh-pages 分支上，然后只需要在 Github 项目设置中选择好对应 GitPage 的分支，然后通过 https://<user-name>.github.io/<project-name> 访问即可。