2022-05-24 mkdocs 配置详情

现在有太多的工具能帮你生成静态网页。这里我用的是 mkdocs，它使用 Python 运行服务/生成静态网页，官方在这里有说明如何使用并配置 mkdocs。

建议使用 Python3。

pip3 install mkdocs mkdocs-video mkdocs-material jieba

初始的 mkdocs 并不够好看好用，但好在很多人为这个模块提供了诸多模块和主题.这里我们使用的主题是 mkdocs-material .

配置

在我的站点主要内容将是中文，以及可能出现的视频和公式，所以我们需要为这些特殊的东西添加一些额外的配置，以让其正常显示。

中文搜索

非常幸运的是，在我着手搭建站点前半个月，mkdocs-material 主题刚刚实现了基于 jieba 模块的中文搜索支持。如果不按照链接进行配置的话，搜索功能就只支持英文，中文是搜不出任何内容的。虽然有些时候效果不好，但起码能用。这也是我选择使用这个主题的主要原因。

视频支持

mkdocs-video 模块支持文章中插入视频并播放，只需配置里写好设置，并按照如下格式插入Markdown中：

![type:video](THE_VIDEO_PATH_HERE)

公式支持

公式显示需要引入额外的 JavaScript文件。具体配置方法见下。

配置分享

以下是个人站点 mkdocs.yml 的部分配置：

theme:
  name: material
  language: zh
  palette:
    primary: green
  features:
    - navigation.expand    # 左侧导航栏自动展开 (不设置的话需要手动点开)
    # - toc.integrate        # TOC集成到左侧导航栏中，不设置的话右侧将单独开一个TOC的导航栏
    - navigation.top       # 回到页面顶部
    - search.suggest       # 搜索建议
    - search.highlight     # 搜索结果高亮显示

plugins:
  - search:
      separator: '[\s\u200b\-\.]'
  - mkdocs-video:
      is_video: True

markdown_extensions:
  # 支持显示 Checklist ( - [ ] 和 - [x] )
  - pymdownx.tasklist:
      custom_checkbox: true
  # - markdown_checklist.extension  # 显示有问题，弃用
  - markdown.extensions.tables
  - pymdownx.magiclink
  - pymdownx.betterem
  - pymdownx.tilde
  - pymdownx.emoji
  - pymdownx.superfences

extra_javascript:
    # 支持公式显示
    - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'

此外还可以修改图标，添加 .css 和 .js 来实现更独特的网页效果，因为搭建站点时没有修改这些内容，在此不做介绍。

说实话，配置完这些我理解为什么 Typora 要收费了，因为这些看似不起眼的地方为了能让用户傻瓜式的使用，都是需要花时间调配的。