• 发布于 2026年8月11日
• 更新于 2026年8月11日
• 分类于 编程
• 阅读时长 12 分钟

MaterialX for MkDocs 使用笔记

MaterialX是Material for MkDocs的兼容继承者，保留了MkDocs的配置方式和大部分Material生态，同时增加了Steps、代码折叠、内置日期等功能。本文只记录日常建站和写作中最常用的配置，示例基于MaterialX 10.2.x + MkDocs。

使用原则

优先查阅MaterialX官方文档。MaterialX继承的通用功能也可以参考Material for MkDocs文档。

1 安装与运行

1.1 安装MaterialX

建议使用独立的Python环境。本文使用Conda：

conda create -n mkx python=3.12
conda activate mkx
pip install mkdocs-materialx

mkdocs-materialx会自动安装兼容版本的MkDocs、Markdown和Pymdown Extensions，不需要再单独安装这些基础依赖。

长期维护的网站建议使用requirements.txt记录依赖：

requirements.txt

mkdocs-materialx
mkdocs-document-dates
mkdocs-glightbox
mkdocs-feed

安装依赖

pip install -r requirements.txt

需要完全复现环境时，可以使用pip freeze生成带版本号的依赖文件。

1.2 创建站点

在空文件夹中执行：

mkdocs new .

生成的基础结构如下：

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

• mkdocs.yml：网站配置文件。
• docs/：Markdown文章、图片、CSS和JavaScript等源文件。
• site/：执行构建后生成的静态网站，不要直接修改。

最小配置：

mkdocs.yml

site_name: My Site
site_url: https://example.com/

theme:
  name: materialx
  language: zh

1.3 预览与构建

实时预览

mkdocs serve

默认访问http://127.0.0.1:8000/。大型站点只修改当前文章时，可以使用mkdocs serve --dirtyreload缩短重建时间。

构建网站

mkdocs build --strict

构建结果位于site/。--strict会将警告视为错误，适合部署前检查配置和链接。

2 核心配置

2.1 推荐起点

下面的配置包含中文界面、导航、搜索、代码块、提示框、Tabs、Grid、图标和数学公式等常用功能：

mkdocs.yml

site_name: My Site
site_url: https://example.com/
site_author: Your Name
site_description: 网站简介

repo_name: username/repository
repo_url: https://github.com/username/repository

nav:
  - 首页: index.md
  - 技术:
      - code/index.md
      - Python: code/python.md
  - 关于: about.md

theme:
  name: materialx
  language: zh
  palette:
    primary: blue grey
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.tabs
    - navigation.indexes
    - navigation.top
    - content.code.copy
    - content.code.annotate
    - search.highlight
    - toc.follow

plugins:
  - search

markdown_extensions:
  - admonition
  - attr_list
  - footnotes
  - md_in_html
  - tables
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

配置可以分为以下几部分：

配置	作用
site_*	网站名称、地址、作者和简介
nav	页面顺序与导航层级
theme	主题外观和交互功能
plugins	构建阶段生成搜索、博客、标签等内容
markdown_extensions	扩展Markdown语法
extra_css、extra_javascript	加载自定义样式和脚本

Warning

YAML只能使用空格缩进，不能使用Tab。site_url应填写网站最终地址，GitHub项目站通常为https://username.github.io/repository/。

2.2 导航

nav:
  - 首页: index.md
  - Code:
      - code/index.md
      - Languages:
          - Python: code/python.md
          - Git: code/git.md
  - 关于: about.md

nav中的路径以docs/为起点。启用navigation.indexes后，栏目中的第一个index.md可以作为栏目首页：

theme:
  features:
    - navigation.indexes

常用导航功能：

功能	说明
navigation.tabs	一级栏目显示在顶部
navigation.tabs.sticky	顶部栏目滚动后仍然显示
navigation.sections	侧栏按栏目分组
navigation.indexes	允许栏目标题链接到index.md
navigation.expand	默认展开侧栏目录
navigation.top	显示返回顶部按钮
navigation.tracking	地址栏跟随当前标题锚点
navigation.prune	大型站点只输出必要的导航HTML
toc.follow	右侧目录跟随阅读位置滚动

navigation.prune与navigation.expand的用途相反，不建议同时启用。

2.3 Instant Navigation

theme:
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress

启用后，站内跳转不再完整刷新页面。自定义JavaScript如果需要在每次换页后执行，应使用MaterialX提供的document$：

document$.subscribe(function () {
  // 每次页面切换后重新初始化
})

只监听DOMContentLoaded的脚本通常只会在第一次打开网站时执行。

2.4 颜色、顶栏与Logo

theme:
  name: materialx
  topbar_style: primary  # glass、primary、accent
  logo: assets/brand/logo.svg
  favicon: assets/brand/favicon.png
  palette:
    primary: blue grey
    accent: indigo

需要跟随系统切换明暗主题时：

theme:
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

也可以使用内置图标代替Logo图片：

theme:
  icon:
    logo: material/library

2.5 代码折叠

MaterialX可以自动折叠过长的代码块：

theme:
  code:
    fold:
      enabled: true

3 内容组织

3.1 Front Matter

Markdown文件顶部的一对---之间可以填写页面元数据：

---
title: Git使用笔记
description: Git常用命令与问题记录
created: 2026-08-01
updated: 2026-08-11
authors:
  - sevenalist
tags:
  - Git
  - 开发工具
icon: material/git
status: new
hide:
  - toc
---

字段	作用
title	页面标题，也会用于搜索和浏览器标题
description	页面摘要
created、updated	创建和修改日期
authors	作者ID列表
tags	页面标签
icon	页面图标
status	页面状态，如new、deprecated
hide	隐藏navigation或toc
template	为页面指定自定义模板

图标名称可以在MaterialX图标搜索中查找。

3.2 日期与作者

MaterialX提供document-dates插件，可以自动读取文件或Git记录中的时间，也允许Front Matter覆盖：

mkdocs.yml

plugins:
  - document-dates:
      position: bottom
      type: date
      show_created: true
      show_updated: true
      show_author: true
      exclude:
        - index.md
        - blog/*

Front Matter

---
created: 2026-08-01
updated: 2026-08-11
authors:
  - sevenalist
---

在docs/authors.yml中补充作者资料：

docs/authors.yml

authors:
  sevenalist:
    name: Sevenalist
    avatar: assets/brand/avatar.png
    url: https://dengcz.cn/
    email: dengcz.cn@gmail.com
    description: Never Stop Thinking.

3.3 Tags

mkdocs.yml

plugins:
  - tags

Front Matter

---
tags:
  - MkDocs
  - MaterialX
---

目录适合表示稳定的纵向分类，Tags适合表示一篇文章涉及的多个横向主题。

3.4 Blog

mkdocs.yml

plugins:
  - blog:
      blog_dir: world
      post_dir: "{blog}/posts"
      archive: true
      categories: true

docs/
└─ world/
   ├─ index.md
   └─ posts/
      └─ hello.md

博客文章示例：

---
date: 2026-08-11
categories:
  - 技术
tags:
  - MkDocs
slug: hello-materialx
draft: false
---

# Hello MaterialX

这里是正文。

Blog插件会自动生成文章列表，因此不需要将每篇文章都写入nav。

3.5 Meta

多个页面使用相同Front Matter时，可以启用meta插件：

mkdocs.yml

plugins:
  - meta

在目录内创建.meta.yml，其中的元数据会被同目录及子目录页面继承：

docs/code/.meta.yml

tags:
  - 技术笔记
authors:
  - sevenalist

3.6 RSS

安装mkdocs-feed：

pip install mkdocs-feed

mkdocs.yml

plugins:
  - feed:
      timezone: Asia/Shanghai
      filename: feed.xml
      length: 10
      sort_by: created
      full_content: false

4 result演示框

本文使用result容器将语法和实际效果放在同一个演示框中。该写法需要开启md_in_html：

markdown_extensions:
  - md_in_html

基础结构：

<div class="result" markdown>

```markdown
这里放语法源码
```

**效果**

这里放实际渲染内容

</div>

如果主题没有为result提供明显的边框，可以在docs/stylesheets/extra.css中添加：

.md-typeset .result {
  border: .05rem solid rgba(120, 140, 160, .35);
  border-radius: .4rem;
  padding: 0 1em;
}

5 常用写作组件

5.1 Admonition提示框

需要启用：

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

!!! note "普通提示"
    这里是提示内容。

??? tip "点击展开"
    这里是折叠内容。

???+ warning "默认展开"
    这里默认处于展开状态。

效果

普通提示

这里是提示内容。

点击展开

这里是折叠内容。

默认展开

这里默认处于展开状态。

常用类型包括note、abstract、info、tip、success、question、warning、failure、danger、bug、example和quote。

5.2 Steps步骤

Steps是MaterialX内置组件，需要启用md_in_html。列表项中可以继续嵌套代码块、提示框和Tabs。

<div class="steps" markdown>

1. 安装依赖

    ```bash
    pip install mkdocs-materialx
    ```

2. 修改配置

    将主题名称设置为`materialx`。

3. 启动预览

    ```bash
    mkdocs serve
    ```

</div>

效果

1. 安装依赖

   pip install mkdocs-materialx
   

2. 修改配置

   将主题名称设置为materialx。

3. 启动预览

   mkdocs serve
   

5.3 代码块

代码块可以添加标题、行号、高亮和注释：

```python title="main.py" linenums="1" hl_lines="2"
name = "MaterialX"
print(f"Hello, {name}!")  # (1)
```

1. 代码注释会显示在代码块下方。

效果

main.py

name = "MaterialX"
print(f"Hello, {name}!")  # (1)

1. 代码注释会显示在代码块下方。

复制按钮和代码注释需要启用：

theme:
  features:
    - content.code.copy
    - content.code.annotate

5.4 Content Tabs

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

=== "Windows"

    ```powershell
    .\.venv\Scripts\Activate.ps1
    ```

=== "Linux / macOS"

    ```bash
    source .venv/bin/activate
    ```

效果

WindowsLinux / macOS

.\.venv\Scripts\Activate.ps1

source .venv/bin/activate

启用content.tabs.link后，同名Tabs可以在页面中同步切换：

theme:
  features:
    - content.tabs.link

5.5 Grid Cards

Grid需要attr_list和md_in_html，适合制作首页入口和栏目索引。

<div class="grid cards" markdown>

-   :material-book-open-page-variant: **世界 · 观**

    ---

    关于世界、社会与生活的观察。

    [进入栏目 :material-arrow-right:](/world/index.md)

-   :material-code-tags: **技术笔记**

    ---

    代码、工具与实践记录。

    [查看编程文章 :material-arrow-right:](/world/index.md)

</div>

效果

• 世界 · 观

  ---

  关于世界、社会与生活的观察。

  进入栏目

• 技术笔记

  ---

  代码、工具与实践记录。

  查看编程文章

普通等宽Grid的写法：

<div class="grid" markdown>

第一块内容

第二块内容

</div>

5.6 按钮与图标

按钮需要attr_list，图标需要pymdownx.emoji。

[普通按钮](#buttons){ .md-button }

[主要按钮 :material-arrow-right:](#buttons){ .md-button .md-button--primary }

:material-github: :material-rss: :fontawesome-brands-python:

效果

普通按钮

主要按钮

5.7 图片、说明与灯箱

attr_list可以设置宽度和对齐方式：

<figure markdown="span">
  ![Sevenalist头像](/assets/brand/logo.png){ width="120" }
  <figcaption>使用figure添加图片说明</figcaption>
</figure>

效果

使用figure添加图片说明

需要点击放大时安装并启用GLightbox：

pip install mkdocs-glightbox

mkdocs.yml

plugins:
  - glightbox:
      manual: true

当manual: true时，只在需要灯箱的页面Front Matter中添加：

---
glightbox: true
---

5.8 数学公式

mkdocs.yml

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

还需要根据所选方案加载MathJax或KaTeX脚本。

行内公式：$E=mc^2$

$$
f(x)=\frac{e^x+e^{-x}}{2}
$$

效果

行内公式：\(E=mc^2\)

\[ f(x)=\frac{e^x+e^{-x}}{2} \]

5.9 表格、脚注与键盘

| 指令 | 作用 |
|---|---|
| `mkdocs serve` | 本地预览 |
| `mkdocs build` | 构建网站 |

按下++ctrl+s++保存文件。[^save]

[^save]: `pymdownx.keys`负责渲染键盘按键，`footnotes`负责脚注。

效果

指令	作用
mkdocs serve	本地预览
mkdocs build	构建网站

按下Ctrl+S保存文件。¹

6 自定义样式与脚本

6.1 加载CSS和JavaScript

推荐将自定义文件放在docs目录内：

docs/
├─ stylesheets/
│  └─ extra.css
└─ javascripts/
   └─ extra.js

mkdocs.yml

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

尽量把样式集中在CSS文件中，不要在每篇文章里重复内联<style>。

6.2 模板覆盖

需要修改页面HTML结构时，使用custom_dir：

theme:
  name: materialx
  custom_dir: overrides

overrides/
├─ main.html
└─ partials/

模板覆盖会与主题内部结构耦合，升级MaterialX后应重点检查。仅调整颜色、间距和字体时，优先使用CSS。

6.3 中文标题锚点

跨页面引用的重要标题建议指定稳定的英文ID：

## 提示框 { #admonitions }

[跳转到提示框](#admonitions)

修改中文标题后，只要#admonitions不变，原有链接仍然有效。

7 GitHub Pages部署

项目根目录创建.github/workflows/ci.yml：

.github/workflows/ci.yml

name: ci

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Deploy
        run: mkdocs gh-deploy --force

推送main分支后，工作流会构建网站并发布到gh-pages分支。第一次部署后，在GitHub仓库的「Settings -> Pages」中确认发布来源为gh-pages分支的/(root)目录。

本地手动发布只需要：

mkdocs gh-deploy --force

8 常见问题

8.1 页面效果没有渲染

按以下顺序检查：

1. 语法依赖的markdown_extensions是否已经启用。
2. HTML容器是否包含markdown属性，并已启用md_in_html。
3. Tabs和嵌套代码块是否已启用pymdownx.superfences。
4. 图标是否已配置pymdownx.emoji。
5. 修改mkdocs.yml后是否重新启动了mkdocs serve。

8.2 GitHub Pages样式丢失

项目站应填写包含仓库名的完整地址：

site_url: https://username.github.io/repository/

然后重新执行部署。

8.3 插件导致构建失败

先在本地执行：

mkdocs build --strict

确认requirements.txt包含所有插件。升级前记录当前可用版本，出现兼容问题时根据锁定的依赖回退，不要一次升级全部依赖后再排查。

8.4 大型站点构建缓慢

• 编辑单篇文章时使用mkdocs serve --dirtyreload。
• 启用navigation.prune减小页面中的导航HTML。
• 删除没有实际用途的插件和JavaScript。
• 在CI中缓存~/.cache，但应先确认插件确实生成了该目录。

9 参考资料

• MaterialX Installation
• MaterialX Create your site
• MaterialX Authoring
• MaterialX Date & authors
• MaterialX Publish your site
• MkDocs User Guide

2026-08-112026-08-11

---

1. pymdownx.keys负责渲染键盘按键，footnotes负责脚注。 ↩