Skip to content

Mkdocs

Document

安装 Mkdocs

在 conda 虚拟环境中安装

  • 创建 conda 虚拟环境
conda create --name mkdocs python=3.9
  • 安装 pip
conda install pip
  • 安装 mkdocs
pip install mkdocs

安装 material 主题

pip install mkdocs-material

常用命令

  • 在 mkdocs 命令前要加入 python -m

创建项目

mkdocs new my-project
cd my-project

测试项目

  • 切换到 Doc 目录下
cd D:/Projects/Site/CS-Document
  • 启动测试服务
python -m mkdocs serve

部署文档

  • 目录结构
CS-Doucment/
    mkdocs.yml
    docs/
qiuhong-1202.github.io/
  • 激活 mkdocs 虚拟环境
conda activate mkdocs
  • 转到 Doc 目录编写文档
cd D:/Projects/Site/CS-Document
  • 转到 Pages 仓库目录下
cd ../qiuhong-1202.github.io/
  • 部署到 Github Pages
python -m mkdocs gh-deploy --config-file ../CS-Document/mkdocs.yml --remote-branch main

Debug

  • "git-revision-date-localized" plugin is not installed
    • 安装下列包: pip install mkdocs-git-revision-date-localized-plugin
  • LaTeX 无法换行：这是 MathJax 的 bug，现有的解决方法是在公式块中使用 \displaylines{}
  • 无序标题不支持多层嵌套：需要安装额外插件并启用
    • P.S. 原生的无序标题不是不支持多层嵌套，而是嵌套的前提是第二级标题为 4 个空格而不是 typora 默认的 2 个空格
    • pip install mdx_truly_sane_lists
    • 在 mkdoc.yml 的 markdown_extensions 添加 mdx_truly_sane_lists

参考

Last update: August 1, 2023
Created: May 5, 2023