MkDocs-Material 文档搭建过程

2026年2月15日域主留下评论

记录一下搭建MkDocs-Material的文档站过程。我的学习重心没有放在文档站上，也只会一些菜鸟的配置，因此不推荐当作教程参考，仅仅用作域主事迹记载。

另外由于MkDocs本体未曾更新，MkDocs-Material项目组的开发成员另外推出了Zensical，后续或许是更合适的选择。主要是我有Material偏好加上编辑CSS比较方便（其实不熟悉Git我还是对于编辑同步不知所措）。

安装和使用mkdocs(material)

安装 mkdocs-material 其实自带了mkdocs本体，因此只需通过pip安装即可：

pip install mkdocs-material

创建项目目录：

mkdocs new .

预览：

mkdocs serve

基本信息

编辑 mkdocs.yml
配置网站名称、URL和版权信息：

site_name: 名称
site_url: https://domain.ltd
copyright: Copyright © 2026 版权信息

主题与外观

设置主题、语言、特性以及站点图标

theme:
  name: material
  language: zh
  features:
    - search
    - htmlproofer
    - search.suggest
    - navigation.instant
    - navigation.sections
    - navigation.indexes
    - navigation.expand
    - navigation.tabs
    - header.autohide
    - tags
  favicon: ./assets/favicon.png
  logo: ./assets/sitelogo.png

接下来是配色板，针对系统暗色模式引用自定义样式：

  palette:

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      primary: cyan
      accent: cyan
      toggle:
        icon: material/brightness-auto
        name: Default Light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      primary: black
      accent: cyan
      scheme: v1sta
      toggle:
        icon: material/brightness-7
        name: Dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      primary: cyan
      accent: cyan
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Aurora Mode

引用自定义CSS文件，其文件应存放在docs目录下，引用文件时会将docs作为根目录起始。
如下例的extracss，保存在 [mkdocs目录]/docs/stylesheets目录下：

extra_css:
  - stylesheets/extra.css

创建额外的css配置文件，配置系统的暗色模式支持：

[data-md-color-scheme="v1sta"] {
  --md-primary-fg-color:        #22a2ac;
  --md-primary-fg-color--light: #21d9d9;
  --md-primary-fg-color--dark:  #105474;
  --md-accent-fg-color:#00b0c7;
  --md-typeset-a-color:#00b0c7;
  
  .md-header {
      background-image: linear-gradient(180deg, rgba(0, 0, 0, 1) 1px, rgba(200, 200, 200, 1) 1.2px, rgba(126, 126, 126, 1) 2px, rgba(64, 64, 64, 1) 24px, rgba(25, 25, 25, 1) 24px, rgba(0, 0, 0, 1) 48px, rgba(0, 0, 0, 1) 50px, rgba(20, 20, 20, 1) 100%);;   
  }
  .md-tabs {
    background-color: black;
  }
}
[data-md-color-scheme="slate"] {
  --md-primary-fg-color:        #22a2ac;
  --md-primary-fg-color--light: #00e8e8;
  --md-primary-fg-color--dark:  #105474;
  --md-default-bg-color: #051824;
  --md-code-bg-color: #12252f;
  --md-accent-fg-color:#6de6e6;
  --md-typeset-a-color:#46c8da;
  
  .md-header {
      background-image: linear-gradient(180deg, rgba(0, 0, 0, 1) 1px, rgba(200, 200, 200, 1) 1.2px, rgba(126, 126, 126, 1) 2px, rgba(64, 64, 64, 1) 24px, rgba(25, 25, 25, 1) 24px, rgba(0, 0, 0, 1) 48px, rgba(0, 0, 0, 1) 50px, rgba(20, 20, 20, 1) 100%);;   
      background-blend-mode: luminosity;    
  }
  .md-tabs {
    background-color: black;
  }
}

插件

调用额外插件：

plugins:
  - search
  - ezlinks
  - blog

i18n翻译插件

安装i18n插件：

pip install mkdocs-static-i18n

在plugins部分添加翻译的配置项，例如导航部分的自定义术语：

plugins:
...
  - i18n:
      default_language: zh
      docs_structure: folder
      languages:
        - locale: zh
          default: true
          name: 中文（简体）
          build: true
          nav_translations:
            Command: 命令

未完待续……

一句老话：做菜容易备菜难，mkdocs的配置文件其实很简洁，根据官方手册来都能学会；但更难的问题还是在于如何同步文档。

需要先在本地同步源目录与docs目录的内容，并在docs下使用 mkdocs build 命令构建生成site目录，再就是应该如何把site目录跟VPS上的静态站同步。并且，这一切应该有一种自动化或是控制面板的方式执行。

我真得学一下git和svn的技术。