MkDocs Material - 极速搭建 Material 风格的文档网站本站 https://onlookee.c

引言

本站『ONLOOKEE』就是使用 Mkdocs Material（以下简称 MM）构建的，MM 的功能非常丰富、强大，可配置程序也非常高、非常灵活。

这不在搭建个人网站，由于囊中羞涩，暂时不打算买虚拟主机，选择使用免费的静态站点托管平台来搭建个人网站，我的需求大致如下：

使用 Markdown 进行内容撰写
有目录导航，可自定义，可分组
每篇文档有大纲目录导航
全站搜索
支持暗黑、移动端适配

显然，自己开发，费时费力，毕竟已经有大量现成的解决方案。起初选择了基于 VUE 开发的 Vitepress 来搭建，Vitepress 也基本能满我目前的需求，也顺利的搭建了个人网站。但是 Vitepress 也有几个让人难受的地方，最难受的几个地方如下：

一是生成速度慢，每次一改配置文件，都要卡壳几十秒
二是不支持增量生成，每次都是全站生成，每生成一次，整个站的所有文件都发生了改变
三是目录导航完全由手工编写，有些费劲（貌似可以通过插件解决，未进一步折腾）

后面我遇到了 Mkdocs-Material，MM 完美解决了我在 Vitepress 中的几个痛点：

生成速度快，比 Vitepress 快不少，改完配置很快就生效，至少不用卡壳几十秒
增量生成（其实并不是），至少，没有内容变化的文档，生成后的文件是不会发生变化的
上手比 Vitepress 来得简单（这个比较个人主观）
配置比 Vitepress 来得丰富、灵活
目录导航自动生成（不过，默认情况下也不是很完美，后面有解决方案）

所以，只好无情地抛弃了 Vitepress，转而投入 Mkdocs-Material 的怀抱。

Mkdocs Material 简介

MM 是 MkDocs 的一款强大主题，它基于 Material Design 原则构建，为用户打造美观、响应式且易于导航的文档网站样式。

MkDocs 本身是一个使用 Markdown 编写静态站点的工具，具有简洁的配置和丰富的插件生态系统。而 MM 在其基础上进一步提升了用户体验。它的特色众多，首先是响应式设计，无论是在桌面设备还是移动设备上，都能为用户呈现出良好的阅读体验。

如果你是 Python 党，搭建静态站点选 MM 就对了。

官网：『Material for MkDocs』

三、安装使用

mkdir docs

方式一，直接 pip 安装，会自动安装 Mkdocs

pip install mkdocs-material

方式二，从 Github 克隆（或下载）源码进行安装

git clone https://github.com/squidfunk/mkdocs-material.git
pip install -e mkdocs-material

安装 awesome-pages 插件

pip install mkdocs-awesome-pages-plugin

安装 macros 插件

pip install mkdocs-macros-plugin

创建新站点

mkdocs new .

启动网站，会启动一个本地服务器，启动后，

mkdocs serve --watch-theme

配置站点

配置文件位于站点根目录下的mkdocs.yml，可以配置的项目非常丰富，我们可以在其中配置网站的名称、描述、主题、导航栏、侧边栏、插件等，且每一个配置项目又有众多可选参数，详见『官方设置』。

以下是本站的配置（仅供参考）

site_name: ONLOOKEE
site_url: https://onlookee.cn/
theme:
  name: material
  language: zh
  logo: assets/logo.png
  favicon: assets/favicon.png
  icon:
    previous: fontawesome/solid/angle-left
    next: fontawesome/solid/angle-right
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-sunny
        name: 切换到暗色模式
      primary: red
      accent: cyan
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-night
        name: 切换到亮色模式
      primary: indigo
      accent: lime
  features:
    - navigation.instant            # 即时加载
    - navigation.instant.prefetch   # 即时预取
    - navigation.instant.progress   # 进度指示器
    - navigation.instant.preview    # 全局启用即时预览
    - navigation.tracking           # 锚跟踪（类似点击后）
    - navigation.tabs               # 启用选项卡（最顶层）
    - navigation.tabs.sticky        # 粘性导航选项卡（保持可见）
    - navigation.tabs.sections      # 分段
    - navigation.expand             # 展开所有
    - navigation.path               # 导航路径（面包屑）（没效果）
    - navigation.indexes            # 节索引页
    - toc.follow                    # 锚跟随
    - navigation.top                # 返回顶部按钮
    - navigation.footer             # 启用页脚（上一页、下一页）

    - search.suggest                # 搜索建议
    - search.highlight              # 搜索高亮显示
    - search.share                  # 搜索分享

    - header.autohide               # 自动隐匿头部
plugins:
  - search
  - offline
  - awesome-pages                   # 启用 mkdocs-awesome-plugin
  - macros                          # 启用 mkdocs-macros-plugin
  - tags:
      tags_file: tags.md
      tags_hierarchy: true          # 启用对标记层次结构
      tags_hierarchy_separator: .   # 层次结构分隔符
      shadow: true
      export: true

extra:
  site_url: https://onlookee.cn/    # 上面的 site_url 会被覆盖为 http://127.0.0.1:8000
  homepage: /
  social: # 社交联系
    - icon: fontawesome/brands/github 
      link: https://github.com/xiaowang19
      name: ONLOOKEE
    - icon: fontawesome/brands/gitlab 
      link: https://gitlab.com/xiaowang19
      name: ONLOOKEE
  generator: true

copyright: Copyright &copy; 2024 ONLOOKEE
markdown_extensions:
  - admonition        # 信息块
  - attr_list         # 属性列表
  - footnotes         # 脚注
  - md_in_html        # HTML 中的 Markdown
  - toc:
      title: == 大纲导航 ==
      permalink: true
      permalink_title: 悬停加载
      toc_depth: 6
  - pymdownx.tasklist:      # 任务列表
      custom_checkbox: true
  - pymdownx.highlight      # 语法高亮
  - pymdownx.inlinehilite   # 内联语法高亮
  - pymdownx.critic         # 启用：突出显示文档中添加、删除或更新的部分
  - pymdownx.caret          # 启用：下划线 ^^、上标 ^
  - pymdownx.keys           # 启用：键盘键 ++
  - pymdownx.mark           # 启用：突出显示 == 
  - pymdownx.tilde          # 启用：删除线 ~~、下标 ~
  - pymdownx.details        # 启用：可折叠的 Admonition
  - pymdownx.superfences    # 代码块
  - pymdownx.emoji:         # 表情包
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:       # 自定义图标集
          - overrides/.icons

extra_css:
  - assets/css/custom.css   # 引用自定义 CSS 文件
extra_javascript:
  - assets/js/loader.js     # 引用自定义 JS 文件

采用了自动生成目录导航，也即不要去配置导航配置项nav:，但自动生成的目录导航，显示在目录导航上名称只能是目录名，顺序也无法调整，所以，使用了 awesome-pages 这个插件来解决自定义显示名称与排序的问题。其实，开始的时候，自己也弄了个插件来处理，后面发现了 Awesome Pages 插件，就直接用了，毕竟没必要重复造的轮子我们就不造了。

Awesome Pages

一款简化配置页面标题及其顺序的 MkDocs 插件

安装

pip install mkdocs-awesome-pages-plugin

启用

编辑mkdocs.yml文件：

plugins:
  - awesome-pages

通过在 plugins 部分添加 awesome-pages，即可启用 MkDocs Awesome Pages Plugin。该插件会自动处理文档的目录结构和页面排序。

!!! warning "注意"

如果您的 mkdocs.yml 定义了 nav 或 pages 条目，此插件不会生效

自定义导航

在每一个目录中创建名为 .pages 的文件，并使用 nav 属性来定制该层级的导航。按它们应该在导航中出现的顺序列出文件和子目录。

以下是本站根目录下的 .pages 文件示例：

title: ONLOOKEE

nav:
    - index.md
    - dev
    - soft
    - things
    - think
    - nav
    - blog
    - about.md
    - ...

更详细的配置请参考官方文档：『mkdocs-awesome-pages-plugin』

写作

写作内容的格式是我等程序猿喜欢的 Markdown，在 docs 文件夹下创建 Markdown 文件，就可以了。默认的文件存放位置是 docs，也可以通过配置项 docs_dir 配置文件存放位置。

!!! note "Markdown 简明语法" 如果您还不是很了解 Markdown，请前往『Markdown 简明语法』进一步了解。

打包部署

打包

mkdocs build --site-dir public

打包生成的静态网页，直接扔到服务器上即可。可配置 CI/CD 自动化流程。

Markdown 扩展

MM 内置了一些不错的 Markdown 扩展，详见：『Markdown 扩展』

本文链接：onlookee.cn/dev/python/…

欢迎转载 ~~~ 欢迎收藏 ~~~ 欢迎评论 ~~~