跳转至

Mkdocs

安装

Ubuntu

sudo apt-get install mkdocs

Windows

pip install mkdocs
mkdocs --version # 验证版本

创建

执行命令

mkdocs new my-wiki

目录结构如下：

  • docs：保存 Markdown 文件
    • index.md：默认首页文件
  • mkdocs.yml：配置文件

配置

详见配置

mkdocs.yml
site_name: Site Name
site_author: author
site_dir: site
docs_dir: docs
remote_branch: gh-deploy
dev_addr: 127.0.0.1:4000 # 调试地址及端口
theme:
  name: material # 主题
  language: zh
  logo: assets/images/logo.png
  favicon: assets/images/favicon.png
markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          percent_encode: true # 支持Unicode字符%编码
use_directory_urls: false
nav:
  - Home: index.md

预览

在根目录下执行命令

mkdocs serve

进入 mkdocs.yml 配置的地址，默认为 127.0.0.1:4000.

添加页面

添加 example.md 到 docs 目录下，然后在 mkdocs.yml 中添加一个导航栏指向该文件：

nav:
  - Example: example.md

生成站点

mkdocs build

根目录下即会创建 site 目录，包含输出的文件：

  • site
    • css
    • fonts
    • img
    • js
    • index.html：index.md
    • example
    • index.html：example.md

发布

GitHub

在 GitHub 上创建一个远程仓库 my-wiki，并关联本地 my-wiki：

cd my-wiki
git init
git remote add origin git@github.com:%username%/my-wiki.git

执行命令，推送 site 目录到 gh-pages 分支下：

mkdocs gh-deploy

打开 Settings->Pages 设置 GitHub Pages，文档即会被发布到 https://%username%.github.io/my-wiki/.

主题

Material for MkDocs

pip install mkdocs-material

插件

mkdocs-graphviz

需要先安装 Graphviz.

pip install mkdocs-graphviz

markdown_extensions:
  - mkdocs_graphviz

extra_javascript:
  # support light and dark modes
  - https://cdn.jsdelivr.net/gh/rod2ik/cdn@main/mkdocs/javascripts/massiliaGraphviz.js

digraph G {
    rankdir=LR
    Earth [peripheries=2]
    Mars
    Earth -> Mars
}

其他 WiKi

参考