Material for MkDocs

什么是 MkDocs？

MkDocs 是一个快速、简单且优雅的静态网站生成器，专门用于构建项目文档。它使用 Markdown 文件作为源文件，并生成完全静态的 HTML 网站，非常适合托管在 GitHub Pages、GitLab Pages 或任何静态网站托管服务上。

主要特点

简单易用：使用纯 Markdown 语法编写文档
实时预览：内置开发服务器，支持实时预览
主题丰富：提供多种美观的主题选择
插件生态：丰富的插件扩展功能
快速构建：快速生成静态网站

MkDocs 的核心功能

1. 文档管理

Markdown 支持：完全支持 Markdown 语法，包括表格、代码块、数学公式等
自动导航：根据文件结构自动生成导航菜单
搜索功能：内置全文搜索功能
多语言支持：支持国际化和多语言文档

2. 主题和样式

Material Design：Material for MkDocs 提供现代化的 Material Design 风格
响应式设计：自适应各种设备和屏幕尺寸
暗色模式：支持明暗主题切换
自定义样式：支持 CSS 自定义和主题定制

3. 扩展功能

代码高亮：支持多种编程语言的语法高亮
Mermaid 图表：支持流程图、时序图等图表渲染
数学公式：支持 LaTeX 数学公式渲染
标签和分类：支持内容标签和分类管理

快速开始

安装 MkDocs

安装 MkDocs 和 Material 主题

pip install mkdocs mkdocs-material

查看版本

mkdocs –version


### 创建新项目

``` bash
# 创建新的 MkDocs 项目
mkdocs new my-project
cd my-project

创建后的项目结构：

my-project/
    mkdocs.yml    # 配置文件
    docs/
        index.md  # 首页文档

基本配置

编辑 mkdocs.yml 配置文件：

site_name: 我的文档网站
site_description: 项目文档描述
site_author: Your Name
site_url: https://yourname.github.io/my-project/

# 主题配置
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.sections
    - navigation.expand
    - navigation.top
    - search.highlight
    - search.share
    - content.code.copy

# 导航结构
nav:
  - 首页: index.md
  - 快速开始: getting-started.md
  - 用户指南: user-guide.md
  - API 参考: api-reference.md

# 插件配置
plugins:
  - search:
      lang: zh
  - minify:
      minify_html: true

# Markdown 扩展
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - footnotes
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - attr_list
  - md_in_html

本地开发和预览

启动开发服务器

1 2	`# 启动本地开发服务器 mkdocs serve`

默认在 http://127.0.0.1:8000 查看网站，支持热重载，修改文件后自动更新。

构建静态网站

1 2	`# 构建静态网站到 site/ 目录 mkdocs build`

部署方案

1. GitHub Pages 部署

1 2	`# 自动部署到 GitHub Pages mkdocs gh-deploy`

这个命令会：

构建网站到临时目录
将内容推送到 gh-pages 分支
GitHub Pages 自动发布网站

2. GitLab Pages 部署

创建 .gitlab-ci.yml 文件：

image: python:3.9

pages:
  stage: deploy
  only:
    - main
  script:
    - pip install mkdocs mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public

3. Netlify 部署

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

[build]
  command = "pip install mkdocs mkdocs-material && mkdocs build"
  publish = "site"

[build.environment]
  PYTHON_VERSION = "3.9"

将代码推送到 Git 仓库
在 Netlify 中连接仓库并自动部署

4. Docker 部署

创建 Dockerfile：

FROM python:3.9-alpine

WORKDIR /docs

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

requirements.txt:

1 2	`mkdocs mkdocs-material`

高级功能

1. 自定义主题

可以通过 extra.css 自定义样式：

/* docs/stylesheets/extra.css */
.md-header {
  background-color: #2c3e50;
}

.md-tabs {
  background-color: #3498db;
}

在 mkdocs.yml 中引用：

1 2	`extra_css: - stylesheets/extra.css`

2. 添加评论系统

使用 Giscus 评论系统：

extra:
  comments:
    provider: giscus
    repo_id: your-repo-id
    category_id: your-category-id

3. 添加统计分析

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

常用插件推荐

文档增强插件

pip install mkdocs-mermaid2-plugin
pip install mkdocs-pdf-export-plugin
pip install mkdocs-awesome-pages-plugin
pip install mkdocs-macros-plugin

配置示例

plugins:
  - search
  - mermaid2
  - pdf-export
  - awesome-pages
  - macros

最佳实践

1. 文档结构建议

docs/
├── index.md                 # 首页
├── getting-started/         # 快速开始
│   ├── installation.md
│   └── basic-usage.md
├── user-guide/             # 用户指南
│   ├── configuration.md
│   └── advanced-features.md
├── api/                    # API 文档
│   └── reference.md
├── tutorials/              # 教程
│   └── examples.md
└── assets/                 # 资源文件
    ├── images/
    └── stylesheets/