安装指南

本指南将帮助你快速安装和配置 MkDocs Material。

环境要求

• Python 3.8 或更高版本
• pip 包管理器

安装步骤

1. 安装 MkDocs Material

使用 pip 安装 Material for MkDocs，这将自动安装 MkDocs 及其所有依赖：

pip install mkdocs-material

虚拟环境推荐

建议在虚拟环境中安装，以避免与其他 Python 包冲突：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 安装
pip install mkdocs-material

2. 创建新项目

# 创建项目目录
mkdir my-project
cd my-project

# 初始化 MkDocs
mkdocs new .

这将创建以下文件结构：

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

3. 配置 Material 主题

编辑 mkdocs.yml 文件，添加 Material 主题配置：

site_name: 我的文档站点

theme:
  name: material
  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: 切换到亮色模式

4. 启动开发服务器

mkdocs serve

打开浏览器访问 http://127.0.0.1:8000 即可预览网站。

成功

恭喜！你已经成功搭建了一个 MkDocs Material 网站。

升级

要升级到最新版本：

pip install --upgrade mkdocs-material

卸载

pip uninstall mkdocs-material

常见问题

如何更改网站语言？

在 mkdocs.yml 中添加 language: zh：

theme:
  name: material
  language: zh

如何添加搜索功能？

Material 主题内置搜索功能，只需在 mkdocs.yml 中添加：

plugins:
  - search:
      lang: 
        - zh
        - en

如何自定义颜色？

修改 palette 中的 primary 和 accent 值：

theme:
  palette:
    - scheme: default
      primary: pink
      accent: pink

可选颜色：red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey, white, black