静态网站框架mkdocs+material学习笔记

把静态博客框架从Pelican换成了Mkdocs，搭配mkdocs-material插件/模板使用。把一些细节记在这里，备忘。

问题

Caution

以汉字开头的markdown文件可能导致奇怪的问题。可以数字时间开头，如“2021-03-17”。

安装

pip install mkdocs

# 以下是插件，按需要安装
pip install mkdocs-material
pip install mknotebooks
pip install mkdocs-redirects
pip install mkdocs-macros-plugin

# pip install jieba
# pip install click-man
# click-man --target path/to/man/pages mkdocs

生成项目

mkdocs new your\blog\dir

设置文件

# mkdocs.yml
site_name: 嬉戏实验室
nav: # 导航结构
    - Home: index.md
    - 儿童识字:
        - '2020-06-24-自制儿童启蒙集中识字语料库与分级字表.md'
        - '2020-06-24-自制儿童启蒙集中识字分级字表.md'
    - 老编辑的效率工具:
        - '2018-11-7-奇技淫巧志.md'
        - '两种markdown文件解析方法': '2021-02-04-两种markdown文件解析方法.ipynb' # 原本只支持markdown文件，其他文件需要插件支持，同时可能需要制定标题
    - About: about.md
theme:
    name: material # 指定mkdocs-material模板
    favicon: img/favicon.ico
    logo: img/logo.png
    palette: # 更改配色
        primary: blue grey # 主色
        accent: pink # 强调色
    features:
        - navigation.instant
        - navigation.tabs # 栏头加标签（一级导航）
        - navigation.tabs.sticky # 固定（浏览时不收起）标签
    language: zh
    custom_dir: overrides # 指定模板文件夹，放自定的覆盖模板
markdown_extensions:
    - meta # 支持markdown博客文件头的元数据，比如标题
    - toc:
        permalink: "#"
        baselevel: 1
        separator: "_"
    - footnotes # 支持脚注
    - admonition  # 支持提示块
    - pymdownx.details  # 提示块可折叠
    - attr_list 
    - pymdownx.inlinehilite # 支持行内语法高亮
    - pymdownx.highlight: # 支持代码块语法高亮
        linenums: true # 显示行号
    - pymdownx.superfences # 可在列表等处嵌入块
plugins:
    - mknotebooks:
        enable_default_jupyter_cell_styling: false
        enable_default_pandas_dataframe_styling: false
        # write_markdown: true
    - search: # 搜索
        lang:
            - en
            - ja # 日文，也勉强支持中文
        separator: '[\s\-\.]+' # 分词分隔符
        # prebuild_index: true # 预制索引，不成功
    - macros:
        # 替换默认的jinja宏标志{{}}，否则类似的地方可能报错
        # 或用raw标签包裹
        # 
        j2_block_start_string: '[[%'
        j2_block_end_string: '%]]'
        j2_variable_start_string: '[['
        j2_variable_end_string: ']]'
        #     
    # - redirects: # 重定向，改动文件名时使用
    #     redirect_maps:
    #         path/to/old/file.md: path/to/new/file.md
google_analytics: # 谷歌分析
  - XX-XXXXXXXXX-X
  - auto
extra:
    social: # 社交账号
        - icon: fontawesome/brands/github
          link: https://github.com/Fusyong
        #   name: Fusyong on Github
        - icon: fontawesome/brands/facebook
          link: https://www.facebook.com/Aahuaang/
        #   name: Fusyong on Facebook
        - icon: fontawesome/brands/twitter
          link: https://twitter.com/fusyong
        #   name: Fusyong on Twitter
    # disqus: XXXXXXXX # disqus评论插件

运行服务器

cd your\blog\dir
mkdocs serve

生成发布版本

cd your\blog\dir\
mkdocs build

or清理文件夹后在生成

cd your\blog\dir\
mkdocs build --clean

标题取用顺序

1. 从配置文件的导航配置nav中；
2. 博文元数据的title值；
3. Markdown的第一个1级标题；
4. 博文的文件名。

主题

• mkdocs
• readthedocs
• material

mkdocs-material模板覆盖文件夹overrides的结构

.
├─ .icons/                             # Bundled icon sets
├─ assets/
│  ├─ images/                          # Images and icons
│  ├─ javascripts/                     # JavaScript
│  └─ stylesheets/                     # Stylesheets
├─ partials/
│  ├─ integrations/                    # Third-party integrations
│  │  ├─ analytics.html                # - Google Analytics
│  │  └─ disqus.html                   # - Disqus
│  ├─ languages/                       # Localized languages
│  ├─ footer.html                      # Footer bar
│  ├─ header.html                      # Header bar
│  ├─ language.html                    # Localized labels
│  ├─ logo.html                        # Logo in header and sidebar
│  ├─ nav.html                         # 主导航
│  ├─ nav-item.html                    # 主导航条目
│  ├─ palette.html                     # Color palette
│  ├─ search.html                      # Search box
│  ├─ social.html                      # Social links
│  ├─ source.html                      # Repository information
│  ├─ source-date.html                 # Last updated date
│  ├─ source-link.html                 # Link to source file
│  ├─ tabs.html                        # Tabs navigation
│  ├─ tabs-item.html                   # Tabs navigation item
│  ├─ toc.html                         # Table of contents
│  └─ toc-item.html                    # Table of contents item
├─ 404.html                            # 404错误页
├─ base.html                           # Base template
└─ main.html                           # Default page

下载官方库src中的对应文件，修改后放在上述的本地文件夹overrides中的相应位置。

在导航条目下加一行更新时间

拷贝官方的nav-item.html文件到overrides\partials\nav-item.html，修改其中的一段如下

  <!-- Main navigation item -->
  ...
    <li class="{{ class }}">
      <a href="{{ nav_item.url | url }}" class="md-nav__link">
        {{ nav_item.title }}
      </a>
      <!-- 这里是修改：根据markdown文章的meta数据，显示Status值为new的文章的Modified时间 -->
      {% if nav_item.meta.Status and nav_item.meta.Status == "new" %}
      <font size=0.5em color="grey">
        {{ nav_item.meta.Modified }} 更新
      </font>
      <br>
      {% endif %}
      <!-- 修改结束 -->
    </li>
  ...

提示块插件

设置如下：

markdown_extensions:
    - admonition  # 提示块
    - pymdownx.details  # 提示块可折叠

语法如下:

!!! note "可以双引号中指明标题"
    随便多少缩进文本.

    空行分段.

效果如下：

可以双引号中指明标题

随便多少缩进文本.

空行分段.

note用作CSS类名和默认标题，只能是一个单词例如

!!! hint
    标题会自动大写。

效果如下：

Hint

标题会自动大写。

如果不想要标题则引号内留空""。

!!! important ""
    无标题提示块。

效果是：

无标题提示块。

可以附加额外的CSS类，用空格隔开，会附在type.后：

!!! danger highlight blink "不要在家里做"
    ...

效果：

不要在家里做

...

共支持这些类型

• note, seealso
• abstract, summary, tldr
• info, todo
• tip, hint, important
• success, check, done
• question, help, faq
• warning, caution, attention
• failure, fail, missing
• danger, error
• bug
• example
• quote, cite

mkdocs-macros-plugin宏插件

通过变量和宏释放Mkdocs的威力。号称：

Note

This is more than a plugin: it's a mini-framework!

参考资料

• 插件列表
• 最好的MkDocs插件与定制