MkDocs

MkDocs

背景

最近将博客从之前的Django动态网站改为使用MkDocs+MkDocs-Material搭建的静态网站。

主要原因有如下两点：

1. 之前写博客是在Typora中写完markdown的文件，再通过Django的后台更新上去，每次更新博客比较麻烦。
2. 需要一台云服务器独立部署，有成本。

后面在工作中接触到了MkDocs这个项目，能完美解决我的这两个痛点。就趁着最近工作变动之际，记录下相关问题。

官网

mkdocs.org.

命令

• mkdocs new [dir-name] - Create a new project.
• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

项目层级

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

部署

MkDocs 部署文档

MkDocs-Material 部署文档

当前使用github pages服务部署静态文件，由于不想博客的源文件暴露出去，我将之分为两个项目，一个私有项目Blog-MkDocs存放博客源码，一个公开项目yinkh.github.io做github-pages服务。

自定义域名

GitHub Pages服务的自定义域名功能由CNAME文件实现，MkDocs对此做了特殊支持，在 docs_dir 目录下放置CNAME文件后，编译静态文件的时候会自动带上该文件。custom-domains

手动部署

在Blog-MkDocs项目下，手动向项目yinkh.github.io推送。

cd ..\yinkh.github.io
mkdocs gh-deploy --config-file ..\Blog-MkDocs\mkdocs.yml --remote-branch master

自动部署

参考 Github Pages和Actions，可实现写完博客后，推送至github，之后的工作完全由CI完成。

mkdocs material

项目地址：mkdocs-material

中文搜索支持

chinese-search-support

导航栏单行支持

1. 下载代码，搭建开发环境 customization

2. 按PR中的change修改源码 mkdocs-material/pull/3936

3. 打包新的代码 building-the-theme

4. 打包产物位于material文件夹下，需要下列文件移动至自己项目的overrides文件夹下的：

   material/base.html
   material/partials/header.html
   material/assets/javascripts/bundle.e39167e5.min.js
   material/assets/javascripts/bundle.e39167e5.min.js.map
   material/assets/javascripts/workers/search.c9d2aade.min.js
   material/assets/javascripts/workers/search.c9d2aade.min.js.map
   material/assets/stylesheets/main.39214a4c.min.css
   material/assets/stylesheets/main.39214a4c.min.css.map
   material/assets/stylesheets/palette.a6bdf11c.min.css
   material/assets/stylesheets/palette.a6bdf11c.min.css.map
   

   将 base.html 文件中引用的 bundle.js search.js main.css palette.css 重命名为对应的压缩文件。

mkdocs-material==9.1.11 出现搜索时导航栏不压黑的情况 src/assets/stylesheets/main/components/_tabs.scss:31:

.md-tabs {
    z-index: 1;
}