mkdocs

MkDocs 文档站点生成器

MkDocs 是一款快速、简洁的静态站点生成器，可根据 Markdown 文件构建项目文档。配置使用单个 YAML 文件（mkdocs.yml）。

快速开始

安装

# Install MkDocs
pip install mkdocs

# Verify installation
mkdocs --version

创建新项目

# Create project structure
mkdocs new my-project
cd my-project

# Start development server
mkdocs serve

创建的项目结构：

my-project/
├── mkdocs.yml      # Configuration file
└── docs/
    └── index.md    # Homepage

最简配置

# mkdocs.yml
site_name: My Project
site_url: https://example.com/
nav:
  - Home: index.md
  - About: about.md

核心命令

命令	用途
mkdocs new PROJECT	创建新项目
mkdocs serve	启动开发服务器（localhost:8000）
mkdocs build	将静态站点构建到 site/
mkdocs gh-deploy	部署到 GitHub Pages
mkdocs get-deps	显示所需的软件包

常用选项：

• -f, --config-file FILE - 使用自定义配置文件
• -s, --strict - 遇到警告时失败
• -d, --site-dir DIR - 自定义输出目录
• --dirty - 仅重新构建已更改的文件
• --clean - 构建前清理输出目录

项目结构

project/
├── mkdocs.yml              # Configuration (required)
├── docs/
│   ├── index.md            # Homepage
│   ├── about.md            # Additional pages
│   ├── user-guide/
│   │   ├── index.md        # Section homepage
│   │   ├── getting-started.md
│   │   └── configuration.md
│   ├── img/                # Images
│   │   └── logo.png
│   └── css/                # Custom CSS
│       └── extra.css
└── custom_theme/           # Theme customizations (optional)
    └── main.html

导航配置

# Automatic navigation (alphabetically sorted)
# Omit nav key to auto-generate

# Explicit navigation with sections
nav:
  - Home: index.md
  - User Guide:
      - Getting Started: user-guide/getting-started.md
      - Configuration: user-guide/configuration.md
  - API Reference: api/
  - External Link: https://example.com/

编写文档

内部链接

# Link to another page

[See Configuration](configuration.md)

# Link to page in another directory

[Installation](../getting-started/installation.md)

# Link to section anchor

[See Options](configuration.md#options)

页面元数据

---
title: Custom Page Title
description: Page description for SEO
authors:
  - John Doe
date: 2024-01-01
---
# Page Content Here

代码块

```python
def hello():
    print("Hello, World!")
```

表格

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

主题配置

内置主题

# Default MkDocs theme
theme:
  name: mkdocs
  color_mode: auto           # light, dark, auto
  user_color_mode_toggle: true
  nav_style: primary         # primary, dark, light
  highlightjs: true
  navigation_depth: 2
  locale: en

# ReadTheDocs theme
theme:
  name: readthedocs
  prev_next_buttons_location: bottom
  navigation_depth: 4
  collapse_navigation: true

Material for MkDocs（热门第三方主题）

pip install mkdocs-material

theme:
  name: material
  palette:
    primary: indigo
    accent: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest

自定义 CSS/JavaScript

extra_css:
  - css/extra.css

extra_javascript:
  - js/extra.js
  - path: js/analytics.mjs
    type: module

插件

plugins:
  - search:
      lang: en
      min_search_length: 3
  - tags
  - blog

热门插件：

• search - 全文搜索（内置，默认启用）
• blog - 博客功能（Material 主题）
• tags - 内容分类
• social - 社交媒体卡片

**注意：**定义 plugins 会禁用默认插件。请显式添加 - search。

Markdown 扩展

markdown_extensions:
  - toc:
      permalink: true
      separator: "-"
  - tables
  - fenced_code
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

部署

GitHub Pages

# Deploy to gh-pages branch
mkdocs gh-deploy

# With options
mkdocs gh-deploy --force --message "Deploy docs"

构建到任意主机

# Build static files
mkdocs build

# Files output to site/ directory
# Upload to any static host

自定义域名

创建 docs/CNAME 文件：

docs.example.com

常见工作流

新建文档项目

1. 创建项目：mkdocs new my-docs
2. 在 mkdocs.yml 中编辑 site_name 和 nav
3. 将 Markdown 文件添加到 docs/
4. 预览：mkdocs serve
5. 构建：mkdocs build
6. 部署：mkdocs gh-deploy

快速构建预览

Bash(mkdocs build --dry-run)

如果没有问题：Bash(mkdocs serve -v)（开发预览）。

添加新章节

1. 创建目录：docs/new-section/
2. 添加 index.md 和内容文件
3. 更新 mkdocs.yml 中的 nav
4. 预览并验证链接

自定义主题

1. 设置 theme.custom_dir: custom_theme/
2. 创建与主题结构对应的覆盖文件
3. 使用模板块扩展基础模板

安全预览工作流

1. 检查 MkDocs：Bash(which mkdocs || echo "Install: pip install mkdocs")
2. 试运行构建：Bash(mkdocs build --dry-run)
3. 列出问题：Grep -r "ERROR" site/

详细参考

• **配置选项：**参见 references/configuration.md
• **主题自定义：**参见 references/themes.md
• **插件开发：**参见 references/plugins.md
• **部署策略：**参见 references/deployment.md
• **最佳实践：**参见 references/best-practices.md

---

注意事项

• mkdocs serve 会监视 docs/ 和 mkdocs.yml，但不会监视通过 include_dir 或主题覆盖项引入的文件——编辑 custom_theme/main.html 不会触发重新加载。请重启服务器。
• 在 mkdocs.yml 中定义 plugins: 会禁用默认搜索插件——页面将不再编入索引，搜索框也不会返回任何结果。列出插件时，请务必显式包含 - search。
• mkdocs gh-deploy 会强制推送到 gh-pages——在那里进行的任何手动编辑或部署到那里的其他分支都会被悄然销毁。可以使用 --no-history 保持历史记录整洁，但切勿手动编辑 gh-pages。
• use_directory_urls: true（默认值）会改变链接语义：page.md 会变成 page/，而不是 page.html。原始 Markdown 中在本地作为文件时有效的相对链接，在部署的网站上会失效。
• strict: true 遇到警告（包括无法识别的配置键）时会导致失败——向使用默认主题的配置中添加仅适用于 Material 主题的选项，会导致构建失败，而不仅仅是发出警告。启用 strict 前，请检查主题兼容性。
• Material 主题的 navigation.instant 功能会破坏在页面加载时运行的第三方 JS——分析工具、Mermaid、MathJax 都需要显式使用 document$.subscribe() 钩子，而不是 DOMContentLoaded。
• mkdocs build --dirty 会跳过未更改的文件，但无法检测导航或主题配置的更改——页面会使用过时的导航渲染。有疑问时，请使用 --clean（默认值）或删除 site/。