Mkdocs+GitHub Pages 自动部署教程

安装Mkdocs及MkDocs 入门

参考https://www.mkdocs.org/getting-started/

新建站点

创建好文件夹（即站点目录），进入其中。使用mkdocs new .将当前目录作为站点目录，然后修改mkdocs.yml，比如下面：

后面也可以加入MD拓展等,但基础运行必要的话这些足够了,如下:

markdown_extensions:

- attr_list

- md_in_html

- pymdownx.superfences

- pymdownx.critic

- pymdownx.caret

- pymdownx.keys

- pymdownx.mark

- pymdownx.tilde

其中nav部分用于设置页面左侧的目录栏，可以完全自己制定展开集，上面的nav生成的页面是这样的：

其中每个页面是一个md文件，都要放在docs目录下。

然后在当前目录运行mkdocs serve可以在本地http://127.0.0.1:8000预览结果。

部署站点

1. 在github新建一个空仓库

2. (可选)项目中右边击site/新建.gitignore文件，防止后续mkdocs生成的站点直接上传过去

3. 再本地初始化好仓库(参考上面GitHub新建仓库指引)，依次运行：

4. git init进行仓库初始化

5. git add .将当前所有文件纳入管理

6. git commit -m "first commit"初始提交

7. git branch -M main

8. git remote add origin git@github.com:xxxx/xxxx.git

9. git push -u origin main

10. mkdocs gh-deploy --clean构建本地站点并自动推送到远程gh-pages分支,这条命令会自动生成站点，并创建gh-pages分支（若没有），并推送到远程仓库。

11. 随后在github仓库选择Settings，选择左侧Pages，然后Build and deployment部分(如果没有看是不是自己把仓库默认成Private了👀)选择Deploy from a branch，选择对应的gh-pages的root

12. 然后等待构建即可.

附加

自定义域名

上述默认构建在https://<username>.github.io/<websitename>里，如果希望自定义域名，可以在docs里放上CNAME，里面写上自定义域名，然后setting里填上域名；同时需要在域名管理添加github的CNAME解析。