MkDocs 使用指南

MkDocs 是一个基于 Markdown 的静态站点生成器，专为项目文档而设计。配置简单，构建快速，支持丰富的主题和插件生态。

---

安装

MkDocs 需要 Python 3.8 及以上版本。

# 使用 pip 安装
pip install mkdocs

# 推荐同时安装 Material 主题（最流行的 MkDocs 主题）
pip install mkdocs-material

# 验证安装
mkdocs --version

也可以使用 pipx 隔离安装，避免污染全局环境：

pipx install mkdocs
pipx inject mkdocs mkdocs-material

---

快速开始

# 创建新项目
mkdocs new my-project
cd my-project

# 启动本地预览服务器（支持热重载）
mkdocs serve

# 构建静态站点
mkdocs build

浏览器访问 http://127.0.0.1:8000 即可预览文档站点。mkdocs serve 在你修改文件时会自动刷新页面。

---

项目结构

my-project/
├── mkdocs.yml          # 配置文件（项目根目录）
└── docs/               # 文档源文件目录
    ├── index.md        # 首页
    ├── getting-started.md
    ├── user-guide/
    │   ├── index.md
    │   ├── installation.md
    │   └── configuration.md
    └── api/
        └── reference.md

构建后会生成 site/ 目录，包含所有静态 HTML 文件，该目录应加入 .gitignore。

---

配置文件详解

mkdocs.yml 是整个项目的核心配置文件，使用 YAML 格式。

基础配置

# 站点基本信息
site_name: 我的项目文档
site_url: https://example.com/docs/
site_description: 这是一个示例项目的完整文档
site_author: 张三

# 代码仓库链接（会在页面右上角显示）
repo_name: username/my-project
repo_url: https://github.com/username/my-project
edit_uri: edit/main/docs/  # 开启"编辑此页"功能

导航结构

nav 字段定义左侧导航树。未在 nav 中列出的页面不会出现在导航中，但仍然可以通过链接访问。

nav:
  - 首页: index.md
  - 快速开始: getting-started.md
  - 用户指南:
      - 概述: user-guide/index.md
      - 安装: user-guide/installation.md
      - 配置: user-guide/configuration.md
  - API 参考: api/reference.md
  - 更新日志: changelog.md

省略 nav 时，MkDocs 会按文件系统结构自动生成导航。

主题配置

theme:
  name: material           # 主题名称
  language: zh             # 界面语言
  palette:
    - scheme: default      # 浅色模式
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换至深色模式
    - scheme: slate        # 深色模式
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换至浅色模式
  features:
    - navigation.tabs        # 顶部标签导航
    - navigation.tabs.sticky # 标签栏滚动时固定
    - navigation.sections    # 展开导航分组
    - navigation.expand      # 默认展开所有分组
    - navigation.top         # 返回顶部按钮
    - search.suggest         # 搜索建议
    - search.highlight       # 搜索结果高亮
    - content.code.copy      # 代码块一键复制
    - content.tabs.link      # 内容标签页联动

Markdown 扩展

markdown_extensions:
  # 警告块（Note、Tip、Warning 等）
  - admonition
  - pymdownx.details         # 可折叠的警告块

  # 代码高亮
  - pymdownx.highlight:
      anchor_linenums: true  # 行号可链接
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite    # 行内代码高亮
  - pymdownx.snippets        # 从文件插入代码片段

  # 内容标签页
  - pymdownx.tabbed:
      alternate_style: true

  # 数学公式（需配合 MathJax）
  - pymdownx.arithmatex:
      generic: true

  # 任务列表
  - pymdownx.tasklist:
      custom_checkbox: true

  # 表情符号
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

  # 其他常用扩展
  - tables
  - footnotes             # 脚注
  - attr_list             # 为元素添加 HTML 属性
  - md_in_html            # 在 HTML 块中使用 Markdown
  - toc:
      permalink: true     # 标题可链接锚点
      title: 目录

完整配置示例

site_name: My Project
site_url: https://example.com/
repo_url: https://github.com/user/project
repo_name: user/project
edit_uri: edit/main/docs/

theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: blue
      toggle:
        icon: material/weather-night
        name: 深色模式
    - scheme: slate
      primary: blue
      toggle:
        icon: material/weather-sunny
        name: 浅色模式
  features:
    - navigation.tabs
    - navigation.top
    - search.highlight
    - content.code.copy

nav:
  - 首页: index.md
  - 指南: guide.md

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight
  - pymdownx.superfences
  - tables
  - toc:
      permalink: true

plugins:
  - search:
      lang: zh

---

文档编写

警告块 (Admonitions)

!!! note "提示标题"
    这是一个提示内容。支持 **Markdown** 格式。

!!! warning
    这是一个警告，没有自定义标题。

!!! tip "最佳实践"
    可以在这里写最佳实践建议。

??? example "可折叠示例（默认收起）"
    点击展开后才能看到内容。

???+ info "可折叠（默认展开）"
    使用 `???+` 默认展开。

支持的类型：note abstract info tip success question warning failure danger bug example quote

代码块

```python title="hello.py" linenums="1" hl_lines="2 3"
def greet(name: str) -> str:
    message = f"Hello, {name}!"  # (1)
    return message

print(greet("World"))
```

1. 这是一个代码注释气泡，需要启用 `pymdownx.superfences`

内容标签页

=== "Python"
    ```python
    print("Hello, World!")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello, World!");
    ```

=== "Go"
    ```go
    fmt.Println("Hello, World!")
    ```

表格

| 参数      | 类型     | 默认值  | 说明           |
|-----------|----------|---------|----------------|
| `name`    | `string` | —       | 站点名称       |
| `debug`   | `bool`   | `false` | 启用调试模式   |
| `timeout` | `int`    | `30`    | 超时时间（秒） |

任务列表

- [x] 完成需求分析
- [x] 编写技术方案
- [ ] 开发实现
- [ ] 编写测试
- [ ] 部署上线

脚注

MkDocs 使用 Python-Markdown[^1] 进行渲染。

[^1]: Python-Markdown 是 Python 实现的 Markdown 解析器，支持丰富的扩展。

图片与对齐

<!-- 带标题的图片 -->
![示意图](images/diagram.png "鼠标悬停提示")

<!-- 使用 attr_list 扩展控制对齐 -->
![图片](image.png){ align=right width=300 }

页面元数据 (Front Matter)

每个 Markdown 文件顶部可以通过 YAML front matter 配置页面级属性：

---
title: 自定义页面标题
description: 页面 SEO 描述
icon: material/rocket-launch
status: new          # 导航标签：new / deprecated
hide:
  - navigation       # 隐藏左侧导航
  - toc              # 隐藏右侧目录
  - footer           # 隐藏页脚
---

# 正文从这里开始

---

主题定制

覆盖模板

在项目根目录创建 overrides/ 目录，MkDocs Material 会优先使用其中的模板：

my-project/
├── mkdocs.yml
├── overrides/
│   ├── main.html          # 覆盖主模板
│   └── partials/
│       └── footer.html    # 覆盖局部模板
└── docs/

在 mkdocs.yml 中注册：

theme:
  name: material
  custom_dir: overrides

自定义 CSS 和 JS

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js
  - javascripts/mathjax.js  # MathJax 数学公式支持

docs/stylesheets/extra.css 示例：

/* 修改主色调 */
:root {
  --md-primary-fg-color: #2196F3;
}

/* 自定义代码字体 */
code {
  font-family: "JetBrains Mono", monospace;
}

自定义首页

theme:
  name: material

hooks:
  - hooks/socialmedia.py

Material 主题支持通过 home.html 模板创建完全自定义的首页布局。

---

插件系统

在 mkdocs.yml 中启用插件：

plugins:
  - search:                  # 内置搜索（始终建议开启）
      lang: zh
  - tags                     # 标签系统（Material 主题专属）
  - git-revision-date-localized:  # 显示文件最后修改时间
      enable_creation_date: true
      type: date
  - minify:                  # 压缩 HTML/CSS/JS
      minify_html: true

常用第三方插件

插件	安装	功能
mkdocs-material	pip install mkdocs-material	最流行的主题，含大量内置功能
mkdocs-git-revision-date-localized-plugin	pip install mkdocs-git-revision-date-localized	显示页面 Git 修改时间
mkdocs-minify-plugin	pip install mkdocs-minify-plugin	压缩输出文件
mkdocs-redirects	pip install mkdocs-redirects	页面重定向
mkdocs-awesome-pages-plugin	pip install mkdocs-awesome-pages-plugin	更灵活的页面排序
mkdocs-macros-plugin	pip install mkdocs-macros-plugin	在 Markdown 中使用变量和宏
mkdocstrings	pip install mkdocstrings[python]	从代码注释自动生成 API 文档

mkdocstrings 示例

自动从 Python docstring 生成 API 文档：

# API 参考

## 核心模块

::: mypackage.core
    options:
      show_source: true
      show_root_heading: true
      heading_level: 3

---

部署

部署到 GitHub Pages

MkDocs 内置 GitHub Pages 支持：

# 一键构建并推送到 gh-pages 分支
mkdocs gh-deploy

# 指定远程仓库
mkdocs gh-deploy --remote-name origin

或使用 GitHub Actions 自动化部署，创建 .github/workflows/docs.yml：

name: Deploy Docs

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取完整历史（git-revision-date 插件需要）

      - uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - run: pip install mkdocs-material mkdocs-git-revision-date-localized

      - run: mkdocs gh-deploy --force

部署到 Netlify

在项目根目录创建 netlify.toml：

[build]
  command = "mkdocs build"
  publish = "site"

[build.environment]
  PYTHON_VERSION = "3.11"

同时创建 requirements.txt：

mkdocs>=1.5
mkdocs-material>=9.0

部署到 Vercel

创建 vercel.json：

{
  "buildCommand": "pip install mkdocs-material && mkdocs build",
  "outputDirectory": "site",
  "installCommand": "pip install mkdocs-material"
}

自托管

# 构建静态文件
mkdocs build

# site/ 目录即为完整静态站点，可用任何 Web 服务器托管
# Nginx 示例
server {
    listen 80;
    server_name docs.example.com;
    root /var/www/site;
    index index.html;
    try_files uriuri/ $uri.html =404;
}

---

进阶技巧

多版本文档

使用 mike 插件管理多版本文档：

pip install mike

# 部署 1.0 版本
mike deploy 1.0

# 设置默认版本
mike set-default 1.0

# 部署并设置别名
mike deploy --update-aliases 2.0 latest

在 mkdocs.yml 中配置：

extra:
  version:
    provider: mike
    default: latest

变量和宏

安装 mkdocs-macros-plugin 后可在文档中使用变量：

# mkdocs.yml
plugins:
  - macros

extra:
  version: "2.1.0"
  company: "Acme Corp"

在文档中使用：

当前版本：{{ version }}
公司名称：{{ company }}

条件内容

{% if config.extra.env == "prod" %}
这段内容只在生产环境显示。
{% endif %}

多语言文档

plugins:
  - i18n:
      docs_structure: folder
      languages:
        - locale: zh
          default: true
          name: 中文
        - locale: en
          name: English
          nav_translations:
            首页: Home
            指南: Guide

对应的文件结构：

docs/
├── index.md          # 中文首页（默认语言）
├── index.en.md       # 英文首页
├── guide.md
└── guide.en.md

搜索优化

plugins:
  - search:
      lang: zh
      separator: '[\s​\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

# 为页面单独配置搜索权重

在页面 front matter 中控制搜索：

---
search:
  boost: 2        # 提升搜索权重
  exclude: true   # 从搜索中排除此页
---

---

常用命令速查

mkdocs new [dir]          # 创建新项目
mkdocs serve              # 启动开发服务器
mkdocs serve --dev-addr 0.0.0.0:8080  # 指定地址和端口
mkdocs build              # 构建静态站点
mkdocs build --clean      # 构建前清空 site/ 目录
mkdocs gh-deploy          # 部署到 GitHub Pages
mkdocs --help             # 查看帮助

---