MkDocs + Material 主题文档网站¶

一句话概述：MkDocs 是 Python 写的静态文档生成器，配合 Material 主题可以快速搭建漂亮的项目文档网站，写 Markdown 就能发布专业文档。

核心知识点¶

概念	白话解释
MkDocs	文档生成器 = 把 Markdown 文件变成网站
Material 主题	好看的皮肤 = 谷歌 Material Design 风格
mkdocs.yml	配置文件 = 控制网站结构和外观
nav	导航 = 定义左侧菜单结构
plugins	插件 = 扩展功能（搜索、标签等）
gh-deploy	一键部署 = 推到 GitHub Pages

安装配置¶

# 创建虚拟环境（推荐）
python -m venv docs-env                               # 创建虚拟环境
source docs-env/bin/activate                          # 激活环境

# 安装 MkDocs + Material 主题
pip install mkdocs                                    # 安装 MkDocs 核心
pip install mkdocs-material                           # 安装 Material 主题（v9.7+）

# 验证安装
mkdocs --version                                      # 查看版本

快速开始¶

# 创建新项目
mkdocs new my-docs                                    # 生成项目骨架
cd my-docs                                            # 进入项目目录

# 项目结构
# my-docs/
# ├── docs/                                           # 文档目录
# │   └── index.md                                    # 首页
# └── mkdocs.yml                                      # 配置文件

# 启动开发服务器
mkdocs serve                                          # 本地预览（http://127.0.0.1:8000）
mkdocs serve -a 0.0.0.0:8080                          # 指定端口

配置文件 mkdocs.yml¶

# 站点基本信息
site_name: 我的项目文档                                # 网站标题
site_url: https://example.com                         # 网站地址
site_description: 项目技术文档                          # 网站描述
site_author: 彭文强                                    # 作者

# 使用 Material 主题
theme:
  name: material                                      # 指定 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.instant                              # 即时加载（SPA 体验）
    - navigation.tabs                                 # 顶部标签页导航
    - navigation.sections                             # 侧边栏分组
    - search.suggest                                  # 搜索建议
    - search.highlight                                # 搜索高亮
    - content.code.copy                               # 代码复制按钮
    - content.tabs.link                               # 内容标签页联动

# 导航结构
nav:
  - 首页: index.md                                     # 首页
  - 快速开始:                                          # 分组
    - 安装: getting-started/install.md
    - 配置: getting-started/config.md
  - API 参考:                                          # 另一个分组
    - 核心模块: api/core.md
    - 工具函数: api/utils.md

# 插件
plugins:
  - search:                                           # 搜索插件（内置）
      lang: zh                                        # 中文搜索
  - tags                                              # 标签插件

# Markdown 扩展
markdown_extensions:
  - pymdownx.highlight:                               # 代码高亮
      anchor_linenums: true                           # 行号锚点
  - pymdownx.superfences                              # 代码块增强
  - pymdownx.tabbed:                                  # 内容标签页
      alternate_style: true
  - admonition                                        # 提示框（Note/Warning 等）
  - pymdownx.details                                  # 可折叠内容
  - attr_list                                         # 属性列表
  - md_in_html                                        # HTML 中写 Markdown
  - toc:                                              # 目录
      permalink: true                                 # 锚点链接

Markdown 增强语法¶

<!-- 提示框（Admonition） -->
!!! note "注意事项"
    这是一个注意事项提示框。

!!! warning "警告"
    这是一个警告提示框。

!!! tip "小技巧"
    这是一个技巧提示框。

<!-- 可折叠 -->
??? example "点击展开示例"
    折叠的内容在这里。

<!-- 代码块 + 标题 + 高亮行 -->
```python title="example.py" hl_lines="2 3"
def hello():
    name = "MkDocs"          # 高亮行
    print(f"Hello {name}")   # 高亮行

Python

print("Hello")

Bash

echo "Hello"

## 构建与部署

```bash
# 构建静态网站
mkdocs build                                          # 生成 site/ 目录

# 部署到 GitHub Pages（一键）
mkdocs gh-deploy                                      # 自动推到 gh-pages 分支

# 使用 GitHub Actions 自动部署
# .github/workflows/docs.yml

# GitHub Actions 自动部署配置
name: Deploy Docs
on:
  push:
    branches: [main]                                  # main 分支推送时触发
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4                     # 拉取代码
      - uses: actions/setup-python@v5                 # 安装 Python
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material              # 安装依赖
      - run: mkdocs gh-deploy --force                 # 部署

常见报错¶

报错	原因	解决
`Config file 'mkdocs.yml' does not exist`	不在项目根目录	`cd` 到有 `mkdocs.yml` 的目录
`Theme 'material' not found`	没装 Material 主题	`pip install mkdocs-material`
`Page not found in nav`	导航中引用了不存在的文件	检查 `nav` 路径和文件名
`Error reading page`	Markdown 语法错误	检查文件编码（用 UTF-8）
`Port already in use`	端口被占用	`mkdocs serve -a 0.0.0.0:8080`

速查表¶

# 项目管理
mkdocs new <name>                                     # 创建新项目
mkdocs serve                                          # 本地预览
mkdocs build                                          # 构建网站
mkdocs gh-deploy                                      # 部署 GitHub Pages

# 常用 Material 主题功能
# palette: 颜色方案（支持明暗切换）
# features: 导航增强（instant/tabs/sections）
# plugins: 搜索/标签/博客
# extensions: 代码高亮/提示框/标签页

# 目录结构约定
# docs/           → 文档源文件
# docs/index.md   → 首页
# site/           → 构建输出（.gitignore）
# mkdocs.yml      → 配置文件