Skip to content

MkDocs-Material

介绍

MkDocs 是一款静态文档生成工具，专为 Markdown 打造。

Material for MkDocs 是其最受欢迎的主题之一，观感简洁、优雅。

快速入门

MkDocs

# 安装
pip install mkdocs
# 创建项目
mkdocs new notes
cd notes
# 本地预览站点
mkdocs serve
# 构建静态页面，site 文件夹下
mkdocs build
# 清理旧构建文件中的无用文件，并基于新内容重新构建站点
mkdocs build --clean

Material

# 安装
pip install mkdocs-material

# yaml 配置即可激活
theme:
  name: material

配置

Markdown

https://squidfunk.github.io/mkdocs-material/reference/

使其支持常用的 Markdown 基本语法（markdown_extensions）

  • 标注栏
  • Mermaid
  • 语法高亮
  • Latex

注意

Github、Typora和 MkDocs 的 Markdown 渲染器各不相同。GitHub 和 Typora 的 Markdown 渲染器经过自定义优化，支持较宽松的语法规则；而 MkDocs 使用 Python Markdown 库，严格遵循标准 Markdown 格式。

问题：

一个常见问题是列表缩进：标准要求子列表缩进为 4 个空格，但 Typora 和 GitHub 支持 2 个空格，会导致 MkDocs 渲染列表异常。

解决：

未找到兼容方法，我的解决方法是：

  • 对于已有文件，使用 Python 脚本批量修正缩进格式。
  • 将 Typora 的自动缩进调整为 4 个空格的标准格式，确保后续兼容。

主题

特征（feature）

调色板（palette）

字体

我使用的是霞骛文楷

根据 cdn 配置

\docs\stylesheets\extra.css

body {
    font-family: "LXGW WenKai Screen", sans-serif;
}

mkdocs.yml

extra_css:
  - stylesheets/extra.css
  - https://cdn.staticfile.org/lxgw-wenkai-screen-webfont/1.7.0/lxgwwenkaiscreen.css

导航

🚧TODO

Github-Pages

https://squidfunk.github.io/mkdocs-material/reference/

https://www.mkdocs.org/user-guide/deploying-your-docs/

第一次推送

# 初始化 git 仓库
git init
# 关联远程仓库（SSH）
git remote set-url origin git@github.com:hezhengdong/notes.git
# 推送 site/ 文件内容至远程仓库 gh-pages 分支根目录
mkdocs gh-deploy

更新

# 清理、构建和部署
mkdocs gh-deploy

简单原理

mkdocs build

按照 mkdocs.yml 配置将 md 文件构建为静态页面，输出到 site/ 目录。

mkdocs gh-deploy

该命令集成了清理、构建和部署的所有操作。

自动将 site/ 目录的内容部署到 GitHub 仓库的 gh-pages 分支。

mkdocs gh-deploy 背后通过一系列 Git 操作完成部署，逻辑大致如下（推测）

# 创建或切换到 gh-pages 分支
git checkout --orphan gh-pages
# 添加并提交 site/ 目录下的所有文件
# - 清空旧的构建文件
git rm -rf .
# - 将 site/ 目录的内容复制到根目录
cp -r site/* .
# 添加 & 提交
git add .
git commit -m "Deploy documentation"
# 强制更改至远程 gh-pages 分支根目录
git push -u origin gh-pages --force

Google-Analytics

🚧TODO

（Google Analytics 似乎有些过于强大~麻烦~了，目前我只是想要一个简单的网站分析工具）