golang 使用模板新增文件_使用mkdocs搭建博客和编写文档

平时比较懒，写的文章和羊拉屎一样，东一点，西一点，散落在各个平台。一直想把所有的文章都放在一个统一的地方，可以起到备份作用，同时也希望有一个自己的窝。

以前也尝试用过 hexo 和 Hugo 这样的静态博客，搭配上主题还是非常舒服的。不过功能上偏向博客需求，如果想定制一些专题写作计划，实现起来比较麻烦。

经过一番折腾，决定把文章签到到文档生成器上，看起来会系统一些，当然也会存在一些问题，比如标签管理和编写时间的缺失。任何计划都有利有弊，还是先做一个出来再说。

选择 mkdocs 还是 sphinx

因为自己主要使用 python 语言，所以还是使用 python 开发的工具会比较有安全感，如果真遇到问题，至少可以通过源码去排查问题。python 其实也有 pelican 这样的静态博客生成器，使用起来也非常方便。在文档生成器上，主要有 2 个主流的：mkdocs 和 sphinx。

很多大佬写的框架都是 sphinx 编写的，比如 requests 库就是通过 sphinx 部署在 readthedocs 平台上。

mkdocs 用来会简单一些，而且越来越多的新框架使用 mkdocs 编写文档，像 web 开发框架 FastAPI。看了一下 sphinx 和 mkdocs 的官方文档，mkdocs 会清晰一些， sphinx 看起来有点复杂。又查看了 GitHub 上面两个库的 star 数，最后还是选择用 mkdocs。

安装 mkdocs

mkdocs 使用 python 语言编写，先要下载 python 环境，然后通过 pip 安装：

pip install mkdocs

接下来使用 mkdocs 命令进行操作，命令主要有 4 个：

• build, 把 markdown 文档转成 html 页面，在网页中呈现的效果就是 build 之后的 html 文档；
• gh-deploy, 部署文档到 GitHub Pages, 主要作用是把生成的 HTML 文档放到 gh-pages 分支当中，然后让 GitHub Pages 显示 gh-pages 分支当中 HTML 页面；
• new 生成一个新的项目，其实就是创建一个 mkdocs.yml 的配置文件和 doc 目录存储 markdown 文件；
• serve 运行服务器，通过自己的方式在本地或服务器部署，内部是使用 tornado 作为服务器运行。

先在任意目录下创建一个项目：

mkdocs new .

此时目录下会有一个 mkdocs.yml 文件和一个 docs/ 的子目录，子目录下面有一个 index.md 的文件。

在 mkdocs 中写文章

docs/index.md 文件就是整个项目的首页，在本地开启服务：

mkdocs serve

通过浏览器访问 http://localhost:8000， 就可以看到 index.md 当中的内容了。 如果有新的文章，直接在 docs 目录下创建 markdown 文件。需要创建专题或者分类，可以创建子文件夹，mkdocs 默认会把这些文件放到导航栏展示出来。

修改主题

mkdocs 可以修改主题，改变页面的展示效果。修改为内置主题只需要在 mkdocs.yml 文件中添加 theme 配置选项：

theme: name: readthedocs

再次访问页面，网站的展示就变成了 readthedocs 样式了。readthedocs 主题是自带的，不需要额外安装。 如果需要安装第三方的主题，先要安装才可以使用。我们来看一下 FastAPI 的文档主题 mkdocs material, 这个主题在 GitHub 上有 5.1k 的 star, 非常火爆。首先通过 pip 安装：

pip install mkdocs-material

再配置 mkdocs.yml 文件, 就可以使用这个模板了。

theme: 
  name: material

mkdocs 也支持自定义主题。这里就不折腾了，感兴趣的可以自己查资料。

配置导航

mkdocs material 主题 默认是不配置导航的，要开启主题的功能，继续配置 mkdocs.yml 文件，要获得各种效果，基本上只需要配置这个文件。

theme: name: materialfeatures: - navigation.tabs

有时候你并不想把所有的目录都作为导航 tab 展示出来，你需要自己定义导航，同样可以在 mkdocs.yml 文件当中配置。可以嵌套多级路径，但是只有顶层会显示在 tab 中，剩下的会在侧边栏展示。

nav:- 首页: index.md- 编程: - python: python/index.md- golang: golang/index.md

网站风格设置

官方网站有非常多风格设置的说明，可以设置外观颜色，markdown 进阶语法和 emoji 表情等等。下面是一个参考的 mkdocs.yaml 设置：

site_name: My Docstheme: name: material# 设置中文language: zhpalette:# 主色调primary: brownfeatures: - navigation.tabsnav:- 首页: index.md- 编程: - python: python/index.md- golang: golang/index.mdmarkdown_extensions:- admonition- attr_list- codehilite:guess_lang: falselinenums: false- toc:permalink: true- footnotes- meta- def_list- pymdownx.arithmatex- pymdownx.betterem:smart_enable: all- pymdownx.caret- pymdownx.critic- pymdownx.details- pymdownx.emoji:emoji_generator: !!python/name:pymdownx.emoji.to_png- pymdownx.inlinehilite- pymdownx.magiclink- pymdownx.mark- pymdownx.smartsymbols- pymdownx.superfences- pymdownx.tasklist- pymdownx.tilde

发布到 GitHub Pages

第一步：在 github 账号上创建一个库名为： .github.io，把远程仓库的名称添加到本地仓库：

git remote add github https://github.com/yourname/yourname.github.io.git

第二步：生成对应的 HTML 文档，文档会被放到 gh-pages 分支下：

mkdocs gh-deploy

第三步：把本地仓库 push 到远程仓库地址，注意要把 master 分支和 gh-pages 分支都推送：

git push github --all

这里的 github 是远程仓库的名称，你也可以取其他的名字。第四步：在 github 的项目设置里设置默认分支为 gh-pages 分支: 访问 looker53.github.io 就可以看到项目了。