跳转至

静态网站框架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 mkdocs-mermaid2-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 # [定制主页](https://github.com/squidfunk/mkdocs-material/issues/1996)
    - 儿童识字:
        - '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: # 支持代码块语法高亮,!!!跟mermaid冲突
    #     linenums: true # 显示行号
    - pymdownx.superfences: # 可在列表等处嵌入块
        # make exceptions to highlighting of code:
        custom_fences:
            - name: mermaid
              class: mermaid
              format: !!python/name:mermaid2.fence_mermaid
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 # 预制索引,不成功
    - mermaid2:
        arguments:
            securityLevel: 'loose'
    - 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-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!

参考资料#