mkdocs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MkDocs Documentation Site Generator

MkDocs 文档站点生成器

MkDocs is a fast, simple static site generator for building project documentation from Markdown files. Configuration uses a single YAML file (

mkdocs.yml

MkDocs 是一款快速、简洁的静态站点生成器，用于将Markdown文件构建为项目文档。配置仅需单个YAML文件（

mkdocs.yml

）。

Quick Start

快速开始

Installation

安装

bash

undefined

bash

undefined

Install MkDocs

pip install mkdocs

Verify installation

mkdocs --version

undefined

mkdocs --version

undefined

Create New Project

创建新项目

bash

undefined

bash

undefined

Create project structure

mkdocs new my-project cd my-project

Start development server

mkdocs serve


**Project Structure Created:**

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

undefined

mkdocs serve


**生成的项目结构：**

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

undefined

Minimal Configuration

基础配置

yaml

undefined

yaml

undefined

mkdocs.yml

site_name: My Project site_url: https://example.com/ nav:

Home: index.md
About: about.md

undefined

site_name: My Project site_url: https://example.com/ nav:

Home: index.md
About: about.md

undefined

Core Commands

核心命令

Command	Purpose
`mkdocs new PROJECT`	Create new project
`mkdocs serve`	Start dev server (localhost:8000)
`mkdocs build`	Build static site to `site/`
`mkdocs gh-deploy`	Deploy to GitHub Pages
`mkdocs get-deps`	Show required packages

Common Options:

```
-f, --config-file FILE
```
- Use custom config file
```
-s, --strict
```
- Fail on warnings
```
-d, --site-dir DIR
```
- Custom output directory
```
--dirty
```
- Only rebuild changed files
```
--clean
```
- Clean output before build

命令	用途
`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 Structure

项目结构

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

project/
├── mkdocs.yml              # 配置文件（必填）
├── docs/
│   ├── index.md            # 首页
│   ├── about.md            # 附加页面
│   ├── user-guide/
│   │   ├── index.md        # 章节首页
│   │   ├── getting-started.md
│   │   └── configuration.md
│   ├── img/                # 图片目录
│   │   └── logo.png
│   └── css/                # 自定义CSS目录
│       └── extra.css
└── custom_theme/           # 主题自定义目录（可选）
    └── main.html

Navigation Configuration

导航配置

yaml

undefined

yaml

undefined

Automatic navigation (alphabetically sorted)

自动导航（按字母顺序排序）

Omit nav key to auto-generate

省略nav键即可自动生成

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/

undefined

nav:

Home: index.md
用户指南:
- 快速开始: user-guide/getting-started.md
- 配置: user-guide/configuration.md
API参考: api/
外部链接: https://example.com/

undefined

Writing Documentation

文档编写

Internal Links

内部链接

markdown

undefined

markdown

undefined

Link to another page

链接到另一页面

See Configuration

查看配置

Link to page in another directory

链接到其他目录下的页面

Installation

安装说明

Link to section anchor

链接到章节锚点

See Options

undefined

查看选项

undefined

Page Metadata

页面元数据

yaml

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

yaml

---
title: 自定义页面标题
description: 用于SEO的页面描述
authors:
  - John Doe
date: 2024-01-01
---

Page Content Here

页面内容

undefined

undefined

Code Blocks

代码块

markdown

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

markdown

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

Tables

表格

markdown

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

markdown

| 表头1 | 表头2 |
| -------- | -------- |
| 单元格1   | 单元格2   |

Theme Configuration

主题配置

Built-in Themes

内置主题

yaml

undefined

yaml

undefined

Default MkDocs theme

默认MkDocs主题

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

ReadTheDocs主题

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

undefined

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

undefined

Material for MkDocs (Popular Third-Party)

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

bash

pip install mkdocs-material

yaml

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

bash

pip install mkdocs-material

yaml

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

Custom CSS/JavaScript

自定义CSS/JavaScript

yaml

extra_css:
  - css/extra.css

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

yaml

extra_css:
  - css/extra.css

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

Plugins

插件

yaml

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

Popular Plugins:

```
search
```
- Full-text search (built-in, enabled by default)
```
blog
```
- Blog functionality (Material theme)
```
tags
```
- Content categorization
```
social
```
- Social media cards

Note: Defining
plugins
disables defaults. Add
- search
explicitly.

yaml

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

热门插件：

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

注意： 定义
plugins
会禁用默认插件，需显式添加
- search
以启用搜索功能。

Markdown Extensions

Markdown扩展

yaml

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

yaml

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

Deployment

部署

GitHub Pages

bash

undefined

bash

undefined

Deploy to gh-pages branch

mkdocs gh-deploy

With options

mkdocs gh-deploy --force --message "Deploy docs"

undefined

mkdocs gh-deploy --force --message "Deploy docs"

undefined

Build for Any Host

为任意主机构建

bash

undefined

bash

undefined

Build static files

mkdocs build

Files output to site/ directory

Upload to any static host

undefined

undefined

Custom Domain

自定义域名

Create

docs/CNAME

file:

docs.example.com

创建

docs/CNAME

文件：

docs.example.com

Common Workflows

常见工作流

New Documentation Project

新建文档项目

Create project:
```
mkdocs new my-docs
```
Edit
```
mkdocs.yml
```
with site_name and nav
Add Markdown files to
```
docs/
```
Preview:
```
mkdocs serve
```
Build:
```
mkdocs build
```
Deploy:
```
mkdocs gh-deploy
```

创建项目：
```
mkdocs new my-docs
```
编辑
```
mkdocs.yml
```
，设置site_name和导航
向
```
docs/
```
目录添加Markdown文件
预览：
```
mkdocs serve
```
构建：
```
mkdocs build
```
部署：
```
mkdocs gh-deploy
```

Quick Build Preview

快速构建预览

Bash(mkdocs build --dry-run)

If clean:

Bash(mkdocs serve -v)

(dev preview).

Bash(mkdocs build --dry-run)

若检查无问题：执行

Bash(mkdocs serve -v)

启动开发预览。

Add New Section

添加新章节

Create directory:
```
docs/new-section/
```
Add
```
index.md
```
and content files
Update
```
nav
```
in
```
mkdocs.yml
```
Preview and verify links

创建目录：
```
docs/new-section/
```
添加
```
index.md
```
及相关内容文件
更新
```
mkdocs.yml
```
中的
```
nav
```
配置
预览并验证链接

Customize Theme

自定义主题

Set
```
theme.custom_dir: custom_theme/
```
Create override files matching theme structure
Use template blocks to extend base templates

设置
```
theme.custom_dir: custom_theme/
```
创建与主题结构匹配的覆盖文件
使用模板块扩展基础模板

Safe Preview Workflow

安全预览工作流

Check MkDocs:

Bash(which mkdocs || echo "Install: pip install mkdocs")

Dry-run build:
```
Bash(mkdocs build --dry-run)
```
List issues:
```
Grep -r "ERROR" site/
```

检查MkDocs是否安装：

Bash(which mkdocs || echo "Install: pip install mkdocs")

试运行构建：
```
Bash(mkdocs build --dry-run)
```
列出问题：
```
Grep -r "ERROR" site/
```

Detailed References

详细参考

Configuration options: See references/configuration.md
Theme customization: See references/themes.md
Plugin development: See references/plugins.md
Deployment strategies: See references/deployment.md
Best practices: See references/best-practices.md

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