跳转至

Material 主题设置

MkDocs 官方内置了两个主题，mkdocs 和 readthedocs，也可以从 MkDocs wiki 中选择第三方主题或者自定义主题。其中很多已经年久失修，只有 Material for MkDocs 是效果最好且持续更新的，实在是不二之选。

Material Design 主题官网：https://squidfunk.github.io/mkdocs-material

pip install mkdocs-material #使用 pip 进行安装

pip install --upgrade mkdocs-material #升级

pip show mkdocs-material #检查当前安装的版本

1. 配置 mkdocs.yml 示例

site_name: 随笔刻舟   #网站名称
site_description: 人文与自然  #站点描述
site_url: https://example.com  #站点网址 URL，根可位于域名的子目录中
site_author: 佚名   #作者
copyright: Copyright &copy; 2016-2022 佚名 <a href="https://beian.miit.gov.cn/" target="_blank">您的备案号</a> #版权声明与网站备案号

theme:  #主题
  name: material  #名称
  language: zh    #语言，可设置多套切换
#  direction: ltr  #默认ltr从左到右，rtl则从右到左
#  logo: assets/logo.png  #logo图片
  icon:
    logo: material/library  #默认logo图标
#  favicon: images/favicon.png  #网站图标，图像必须位于docs文件夹中
  features:  #导航
    - navigation.instant  #即时加载
    - navigation.tracking  #锚点跟踪
    - navigation.tabs  #导航选项卡
    - navigation.tabs.sticky  #粘性导航选项卡
    - navigation.sections  #次级目录在侧边栏中呈现为组，与tabs同存则有2级导航
#    - navigation.expand  #左侧边栏全展开，取消则折叠其他只展开当选
    - navigation.indexes  #次级索引页，直接将文档附加到章节，提供概览页面，在相应文件夹中创建index.md添加到导航nav开头。不兼容toc.integrate。
    - toc.follow   #锚跟随，文章小标题目录侧边栏自动滚动，以便活动锚点始终可见（付费功能）
#    - toc.integrate  #导航集成，文章小标题目录是左侧边栏的一部分
    - navigation.top  #返回顶端
    - search.suggest  #搜索建议，省略回车
    - search.highlight  #搜索词高亮突出显示
    - search.share   #搜索共享
    - header.autohide  #标题自动隐藏
    - announce.dismiss  #标记为已读（付费功能）
  palette:     #切换昼夜模式的颜色，审美差就用默认，专业点就自定义
    - media: "(prefers-color-scheme: light)" 
      scheme: default  #配色方案：浅色模式
      primary: indigo  #原色，默认蓝，用于标题、侧边栏、文本链接和其他几个组件
      accent: indigo  #强调色，默认蓝，可以交互的元素如悬停链接、按钮和滚动条
      toggle:
        icon: material/weather-sunny #图标，太阳
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"  
      scheme: slate  #配色方案：深色模式
      toggle:
        icon: material/weather-night  #图标，月亮
        name: Switch to light mode
  font:  #字体，false 则阻止从Google加载字体
  # 内置隐私插件自动下载和自托管 Web 字体文件，无需阻止。其他字体使用附加样式表 extra.css 。
    text: Roboto  #常规字体，默认Roboto，正文、标题等，300、400、400i和700
    code: Roboto Mono  #等宽字体，默认Roboto Mono，代码块，400

markdown_extensions:  #推荐配置Markdown基本语法及其扩展
  - abbr #缩写或名词
  - pymdownx.snippets  #片段，将任意文件或部分内容嵌入到文档中  
  - admonition  #警告或标注
  - pymdownx.details  #细节折叠
  - pymdownx.superfences  #超级围栏
  - attr_list   #属性列表（按钮-颜色图标）
  - def_list   #定义列表
  - footnotes  #行内脚注
  - meta   #元数据
  - md_in_html  #HTML 中的 Markdown
  - toc:  #目录
      toc_depth: 3 #目录深度，默认6，0则隐藏
#      title: On this page  #默认值，自动获取
#      permalink: true   #每个标题的末尾添加段落符号锚链接，默认false
#      permalink: ⚓︎  #每个标题的末尾添加自定义符号锚链接
#      permalink_title: Anchor link to this section for reference #在悬停时显示并由屏幕阅读器阅读的锚链接的标题
  - tables #表格（未推荐）
  - pymdownx.arithmatex:  #数学公式
      generic: true  
  - pymdownx.betterem:   #粗体斜体
      smart_enable: all
  - pymdownx.caret  #插入角标符号(`^`)
  - pymdownx.mark  #双等号(`==`)
  - pymdownx.tilde  #波浪号(`~`)
  - pymdownx.critic:  #评论家(突出显示建议更改)，未推荐
#      mode: reject #应如何解析标记，默认view查看更改，accept是接受更改，reject是拒绝更改
  - pymdownx.keys   #键盘键和组合  
  - pymdownx.emoji:  #表情符号
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
#      options: #默认无
#        custom_icons: #允许列出要在 Markdown 中使用的附加图标集的文件夹
#          - overrides/.icons
  - pymdownx.highlight  #代码高亮，对代码块（SuperFences）和行内代码块（InlineHilite）的语法突出显示
  - pymdownx.inlinehilite  #行内高亮
  - pymdownx.smartsymbols  #智能符号
  - pymdownx.tabbed:  #内容选项卡
      alternate_style: true  #启用内容选项卡替代样式，必须开启
  - pymdownx.tasklist:  #任务列表
      custom_checkbox: true   #切换复选框的呈现样式，将原生复选框样式替换为漂亮的图标
#      clickable_checkbox: true  #切换复选框是否可点击，默认false，不建议开
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

plugins:  #插件
  - tags
#  - tags:
#      tags_file: tags.md  #指定应使用哪个文件来呈现标签索引，默认无
#  - privacy  #内置隐私插件（付费功能）
#      enabled: !ENV [PRIVACY, false] #默认值true，关闭且本地环境变量示例
#      externals: bundle  #插件遇到外部资产时做什么。默认bundle，自动下载所有外部文件并调整所有引用，report将在构建期间发出警告消息
#      externals_directory: assets/externals  #下载外部资产存储路径，通常不需要更改
#  - social  #内置社交插件（付费功能），在社交媒体上共享项目文档链接时显示的图像
  - search: #搜索
#      lang:   #语言，自动产生最佳结果，不需要设置
#        - en  #英语
#        - ja  #日语
      separator: '[\s\-\.]' #分隔符，空格、减号、点
#      prebuild_index: true  #预构建索引，默认false，已经弃用该选项

extra_javascript:
  - javascripts/baidu-tongji.js  #百度统计
  - javascripts/mathjax.js  #数学公式的JS
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra:
#  version: #版本控制
#    provider: mike
#  homepage: https://example.com  #通常logo链接到主页，这里可修改
  social:  #页脚
    - icon: fontawesome/brands/twitter   #社交链接
      link: https://twitter.com/squidfunk
      name: squidfunk on Twitter  #一般自动提取
    - icon: fontawesome/solid/paper-plane  #电子邮件
      link: mailto:admin@yiruru.com
#  generator: false  #删除通知“Made with Material for MkDocs”，一般不必
#  analytics: #设置站点分析
#    provider: google
#    property: G-XXXXXXXXXX

2. Markdown语法扩展

2.1. 缩写或名词 abbr

技术文档通常会使用许多首字母缩略词，这可能需要额外的解释，尤其是对于项目的新用户。对于这些问题，Material for MkDocs 使用 Markdown 扩展的组合来启用站点范围的词汇表。

markdown_extensions:
  - abbr  #缩写或名词
  - pymdownx.snippets  #片段，将任意文件或部分内容嵌入到文档中

缩写可以使用类似于 URL 和脚注的特殊语法来定义，*[]。

The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

The HTML specification is maintained by the W3C.

Snippets扩展可用于实现一个简单的词汇表，方法是将所有缩写移动到专用文件中，并将其与每个文档末尾的--8<--符号一起嵌入。

#引用的文档
The HTML specification is maintained by the W3C.

#被引词汇表includes/abbreviations.md
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

强烈建议将包含缩写的 Markdown 文件放在文件docs夹之外（这里includes），否则 MkDocs 可能会抱怨未引用的文件。

其他文件（包括源文件）的内容也可以通过使用代码块中的--8<--符号直接嵌入。

Code block with external content
``` title=".browserslistrc"

``` title=".browserslistrc"
last 4 years
```

2.2. 警告或标注 admonition

提供辅助内容的绝佳选择，启用警告，使它们可折叠并在警告中嵌套任意内容。

markdown_extensions:
  - admonition  #警告
  - pymdownx.details  #细节折叠
  - pymdownx.superfences  #超级围栏

警告遵循简单的语法：启用Details，一个块以 !!! 开头，后跟一个用作类型限定符的关键字。块的内容在下一行，缩进四个空格。

!!! note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

默认情况下，标题将等于标题大小写中的类型限定符。但是，可以通过在类型限定符之后添加包含有效 Markdown（包括链接、格式等）的带引号的字符串来更改它

!!! note "Phasellus posuere in sem ut cursus"

如果双引号内没有内容，标题为空，这不适用于可折叠块。

内容块以 ??? 开始，是可折叠块，右侧有一个小切换。??? 多个加号，则默认展开内容。

???+ note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

内联块（即侧边栏），使用inline+end修饰符将它们放置在右侧，或者仅使用inline修饰符将它们放置在左侧。inline 默认为左对齐（rtl则右对齐）。使用inline修饰符必须在将它们放在旁边的内容块之前声明。如果没有足够的空间在块旁边渲染警告，警告将拉伸到视口的整个宽度，例如在移动端。

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! info inline end

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! info inline

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

警告默认类型以及未知类型限定符的后备是 note （笔记）。其他还有：

  • abstract, summary, tldr 摘要，总结
  • info, todo 信息，待办
  • tip, hint, important 提示，暗示，重要
  • success, check, done 成功，检查，完成
  • question, help, faq 问题，帮助，常见问题解答
  • warning, caution, attention 警告，小心，注意
  • failure, fail, missing 失败，错过
  • danger, error 危险，错误
  • bug 漏洞
  • quote, cite 引用，提及

如果要添加自定义警告类型，只需要颜色和*.svg图标。从文件夹中复制图标的代码.icons并将以下 CSS 添加到附加样式表 docs/stylesheets/extra.css

:root {
  --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
  border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
  background-color: rgba(43, 155, 70, 0.1);
  border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
  background-color: rgb(43, 155, 70);
  -webkit-mask-image: var(--md-admonition-icon--pied-piper);
          mask-image: var(--md-admonition-icon--pied-piper);
}

mkdocs.yml中启用

extra_css:
  - stylesheets/extra.css

实际应用

!!! pied-piper "Pied Piper"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
    purus auctor massa, nec semper lorem quam in massa.

Pied Piper

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

SuperFences扩展允许在彼此之间任意嵌套代码和内容块，包括警告、选项卡、列表和所有其他元素。流程图之类，支持配置选项不多，有风险。

2.3. 属性列表-按钮-颜色图标 attr_list

属性列表扩展允许使用特殊语法将 HTML 属性和 CSS 类添加到几乎每个Markdown 内联和块级元素。

此配置允许使用简单的语法为所有内联和块级元素添加属性，将任何链接变成按钮。为了将链接呈现为按钮，请使用花括号对其进行后缀并将.md-button类选择器添加到其中。如果激活，该按钮将接收选定的原色和强调色。

[Subscribe to our newsletter](#){ .md-button }

Subscribe to our newsletter

如果想显示一个填充的主按钮（例如在MkDocs 的 Material的登录页面.md-button上），同时添加和.md-button--primaryCSS 类选择器。

[Subscribe to our newsletter](#){ .md-button .md-button--primary }

Subscribe to our newsletter

带有图标的按钮

[Send :fontawesome-solid-paper-plane:](#){ .md-button }

Send

align属性在 HTML5 中已被弃用，所以尽量不使用对齐图像、为图像添加标题（将它们呈现为图形）以及标记大图像以进行延迟加载的功能。

attr_list 属性列表-注释（付费功能）。

2.4. 定义列表 def_list

启用定义列表时，可以使用简单的语法枚举任意键值对的列表，例如函数或模块的参数

`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

2.5. 行内脚注 footnotes

脚注引用必须用方括号括起来，开头必须插入符号^，后跟任意标识符，这类似于标准 Markdown 链接语法。

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

Lorem ipsum1 dolor sit amet, consectetur adipiscing elit.2

脚注内容必须使用与引用相同的标识符声明。它可以插入到文档中的任意位置，并且始终呈现在页面底部。此外，会自动添加指向脚注参考的反向链接。

短脚注可以写在同一行：

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

段落可以写在下一行，并且必须缩进四个空格

[^2]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

2.6. 元数据 meta

元数据扩展添加了通过在 Markdown 之前用 YAML 语法编写的前文将任意键值对附加到文档的能力。启用元数据后，在 Markdown 文件的顶部添加以下各行，可实现相应功能。

自定义前端内容覆盖文档的页面标题：

---
title: Lorem ipsum dolor sit amet 
---

自定义前端的文档覆盖页面描述：

---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. 
---

为每个页面分配一个图标，然后将其呈现为导航侧边栏的一部分：

---
icon: material/emoticon-happy 
---

如果使用主题扩展并在目录中创建了新的页面模板 overrides，则可以为特定页面启用它：

---
template: custom.html
---

当同时启用内置标签插件和元数据扩展时，可以为具有自定义前端的文档添加标签。该页面现在将在主标题上方和搜索预览中呈现这些标签，现在允许按标签查找页面：

---
tags:
  - insiders
  - brand new
---

隐藏导航或侧边栏：

---
hide:
  - navigation
  - toc
---

隐藏反馈小部件：

---
hide:
  - feedback
---

2.7. HTML中的Markdown md_in_html

默认情况下，Markdown 会忽略原始 HTML 块级元素中的任何内容。启用扩展后 md_in_html，原始 HTML 块级元素的内容可以通过 markdown 在开始标记上包含属性来解析为 Markdown。该 markdown 属性将从输出中删除，而所有其他属性将被保留。

2.8. 目录 toc

自动从文档生成右侧导航侧栏中的标题目录。

markdown_extensions:
  - toc:
      toc_depth: 3 #目录深度，默认6，0则隐藏
      title: On this page  #默认值，自动获取
      permalink: true   #每个标题的末尾添加段落符号锚链接，默认false
      permalink: ⚓︎  #每个标题的末尾添加自定义符号锚链接
      permalink_title: Anchor link to this section for reference #在悬停时显示并由屏幕阅读器阅读的锚链接的标题
      slugify: !!python/name:pymdownx.slugs.uslugify  #自定义 slug
      slugify: !!python/name:pymdownx.slugs.uslugify_cased   #自定义 slug

2.9. 表格 tables

数据表可以在项目文档中的任何位置使用，并且可以包含任意 Markdown，包括内联代码块，以及图标和表情符号。如果要将特定列左中右对齐，可以使用常规 Markdown 语法将:字符放置在分隔符的开头和或结尾。

|  Method  |             Description              |
| :------ | ----------------------------------: |
|  `GET`   | :material-check:     Fetch resource  |
|  `PUT`   | :material-check-all: Update resource |
| `DELETE` | :material-close:     Delete resource |
Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource

2.10. 数学公式 pymdownx.arithmatex

MathJax是一种在浏览器中显示数学内容的美观且易于访问的方式，增加了对不同符号（例如LaTeX、MathML、AsciiMath）的数学排版的支持。

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

docs/javascripts/mathjax.js文件

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => {
  MathJax.typesetPromise()
})

块必须包含在单独的行$$...$$ 或 \[...\] 中：

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$
\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

内联块必须包含在$...$ 或 \(...\) 中：

The homomorphism $f$ is injective if and only if its kernel is only the 
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
that $f(a)=f(b)$.

The homomorphism \(f\) is injective if and only if its kernel is only the singleton set \(e_G\), because otherwise \(\exists a,b\in G\) with \(a\neq b\) such that \(f(a)=f(b)\).

2.11. 格式化 ^、==、~

markdown_extensions:  
  - pymdownx.caret  #插入角标符号(`^`)  
  - pymdownx.mark   #双等号(`==`)
  - pymdownx.tilde  #波浪号(`~`)
  - pymdownx.critic: #  评论家
      mode: reject #应如何解析标记，默认view查看更改，accept是接受更改，reject是拒绝更改
  - pymdownx.keys   #键盘键和组合

Caret、Mark和Tilde扩展增加了使用简单语法突出显示文本和定义下标和上标的能力。启用Caret、Mark 和 Tilde时，可以使用简单的语法高亮文本，这比直接使用相应的mark,ins和delHTML 标签更方便。

- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
  • This was marked
  • This was inserted
  • This was deleted

还可以使用简单的语法对文本进行下标和上标，这比直接使用相应的HTMLsub标签sup更方便。

- H~2~0
- A^T^A
  • H20
  • ATA

启用 Critic 后，可以使用Critic Markup，它增加了突出显示建议更改以及向文档添加内联注释的功能

Text can be deleted and replacement text added. This can also be
combined into onea single operation. Highlighting is also
possible and comments can be added inline.



Formatting can also be applied to blocks by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

Text can be deleted and replacement text added. This can also be combined into onea single operation. Highlighting is also possible and comments can be added inline.

Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.

启用Keys后，可以使用简单的语法呈现键盘键

++ctrl+alt+del++

Ctrl+Alt+Del

2.12. 表情符号 Emoji

表情符号扩展会自动将*.svg文件格式的捆绑和自定义图标和表情符号内联到生成的 HTML 页面中。

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji 
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options: #默认无
        custom_icons: #允许列出要在 Markdown 中使用的附加图标集的文件夹
          - overrides/.icons

举例

:smile: 
:fontawesome-regular-face-laugh-wink:

😄

2.13. 代码高亮 pymdownx.highlight pymdownx.inlinehilite

Highlight扩展增加了对代码块（在SuperFences的帮助下）和内联代码块（在InlineHilite的帮助下）的语法突出显示的支持。

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true  #代码块行号锚链接，默认false
      use_pygments: true  #在构建期间使用Pygments或在浏览器中使用 JavaScript 语法高亮器进行高亮显示，默认true
      auto_title: true  #自动为所有代码块添加标题，显示正在使用的语言的名称，默认false
      linenums: true #向所有代码块添加行号，默认false
      linenums_style: pymdownx-inline #三种添加行号的方法，建议table或pymdownx-inline。默认table
  - pymdownx.superfences

带有行号的代码块

``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

1
2
3
4
5
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

带标题的代码块

``` py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
bubble_sort.py
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

带有突出显示行的代码块

``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

2.14. 智能符号 pymdownx.smartsymbols

SmartSymbols 添加了用于创建特殊字符（如商标、箭头、分数等）的语法。

Markdown 结果
(tm) ™
(c) ©
(r) ®
c/o ℅
+/- ±
--> →
<-- ←
<--> ↔
=/= ≠
1/4, etc. ¼等
1st 2nd etc. 第1次第2次等
选项 类型 默认 描述
trademark 布尔 True 添加商标符号的语法。
copyright 布尔 True 添加版权符号的语法。
registered 布尔 True 添加注册符号的语法。
care_of 布尔 True 为 care / of 添加语法。
plusminus 布尔 True 添加加/减的语法。
arrows 布尔 True 添加用于创建箭头的语法。
notequal 布尔 True 添加不等号的语法。
fractions 布尔 True 添加常用分数的语法。
ordinal_numbers 布尔 True 为序数添加语法。

2.15. 内容选项卡 pymdownx.tabbed

代码块是要分组的主要目标之一，并且可以被认为是内容选项卡的一种特殊情况，因为具有单个代码块的选项卡总是在没有水平间距的情况下呈现。

=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

警告中的内容选项卡

!!! example

    === "Unordered List"

        ``` markdown title="List, unordered"
        * Sed sagittis eleifend rutrum
        * Donec vitae suscipit est
        * Nulla tempor lobortis orci
        ```

    === "Ordered List"

        ``` markdown title="List, ordered"
        1. Sed sagittis eleifend rutrum
        2. Donec vitae suscipit est
        3. Nulla tempor lobortis orci
        ```

Example

List, unordered
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
List, ordered
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

2.16. 任务列表 pymdownx.tasklist

Tasklist扩展允许使用GitHub Flavored Markdown启发的任务列表，遵循相同的语法约定。

- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
  • Lorem ipsum dolor sit amet, consectetur adipiscing elit
  • Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • In scelerisque nibh non dolor mollis congue sed et metus
  • Praesent sed risus massa
  • Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

2.17. 图表 mermaid

图表有助于传达不同技术组件之间的复杂关系和相互联系，并且是项目文档的重要补充。MkDocs 的 Material 与 Mermaid.js 集成，这是一种非常流行且灵活的绘图解决方案。

此配置启用对Mermaid.js图表的本机支持。当页面包含 mermaid 代码块时将自动初始化 JavaScript 运行。

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

虽然所有Mermaid.js功能都应该开箱即用，但 Material for MkDocs 目前只会调整流程图、序列图、类图、状态图和实体关系图的字体和颜色。举例如下

流程图

``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

序列图

``` mermaid
sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

状态图

``` mermaid
stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]
```

stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]

类图

``` mermaid
classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }
```

classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }

实体关系图

``` mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

2.18. 图片对齐

此配置增加了对齐图像、为图像添加标题（将它们呈现为图形）以及标记大图像以进行延迟加载的功能。

markdown_extensions:
  - attr_list
  - md_in_html

启用属性列表时，可以通过 align 属性添加相应的对齐方向来对齐图像，即 align=left 或 align=right。该align属性不允许居中对齐。

Image, aligned to left
![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

Image title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Image, aligned to right
![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }

Image title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

在 HTML 扩展中使用带有文字 figure 和 figcaption 标签的 Markdown，做图片标题或者说明。

<figure markdown>
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

图片延迟加载

![Image title](https://dummyimage.com/600x400/){ loading=lazy }

3. 其他参考

3.1. 公告栏

向用户显示项目新闻或其他重要信息，当用户滚动过标题时，该栏将自动消失。为了添加公告栏，扩展主题并覆盖默认为空的announce块：

{% extends "base.html" %}

{% block announce %}
  <!-- Add announcement here, including arbitrary HTML -->
{% endblock %}

3.2. 标签

如果文档很大，标签可以更快地发现相关信息。内置标签插件增加了将任何带有标签的页面分类为页面前端的能力。标签将变为可点击，指向标签索引中的相应部分。

plugins: 
  - tags
#  - tags:
#      tags_file: tags.md  #指定应使用哪个文件来呈现标签索引

指定 tags_file 选项不是必需的。如果未指定此选项，标签仍会呈现并可搜索，但没有标签索引。

当同时启用内置标签插件和元数据扩展时，可以为具有自定义前端的文档添加标签。在 Markdown 文件的顶部添加以下行：

---
tags:
  - insiders
  - brand new
---

该页面现在将在主标题上方和搜索预览中呈现这些标签，允许按标签查找页面。

内置标签插件允许定义一个文件来呈现标签索引，它可以是属于该部分的任何页面 nav。要添加标签索引，创建一个页面如 tags.md：

# Tags

Following is a list of relevant tags:

[TAGS]

标记指定标签索引的 [TAGS] 位置，即在呈现页面时将其替换为实际的标签索引。可以在标记之前和之后包含任意内容。

虽然标签呈现在主标题上方，但有时可能需要为特定页面隐藏它们，这可以通过使用元数据扩展来实现：

---
hide:
  - tags
---

3.3. 被取代的基本扩展

围栏代码块 Fenced Code Blocks → 超级围栏 SuperFences

SuperFences扩展在许多方面都更胜一筹，因为它允许任意嵌套。但是，原围栏还可以用。那就看需求了，尽量使用最基本的语法，不要搞复杂，方便移植。

代码/语法突出显示CodeHilite → 代码高亮Highlight

3.4. 添加一个 git 仓库

存储库的链接将呈现在大屏幕上的搜索栏旁边，并作为较小屏幕尺寸的主导航抽屉的一部分。此外，对于托管在GitHub或GitLab上的公共存储库，会自动请求和呈现星号和分叉的数量。

repo_url: https://github.com/squidfunk/mkdocs-material  #存储库URL
repo_name: squidfunk/mkdocs-material  #存储库名称，一般自动设置
theme:
  icon:
    repo: fontawesome/brands/git-alt  #存储库图标
edit_uri: edit/master/docs/  #每个文档的顶部显示一个编辑按钮，""则隐藏
plugins:
  - git-revision-date #每页底部显示文档最后更新日期，安装 pip install mkdocs-git-revision-date-plugin
  - git-revision-date-localized  #每个页面底部添加本地化更新和创建日期，安装pip install mkdocs-git-revision-date-localized-plugin
      type: date  #日期格式，有效值为date、datetime、iso_date、iso_datetimetimeago
      fallback_to_build_date: true  #默认false，启用则回退到mkdocs build执行的时间
      enable_creation_date: true  #最后更新日期旁边显示与页面关联的文件的创建日期

3.5. 省略内容

所有付费功能都省略了，包括：离线插件、隐私插件、目录锚点如下、注释、导航图标、代码注释：锚链接、代码注释：去除注释、可关闭的公告栏、此页面是否有帮助？、全新的搜索插件、丰富的搜索预览、具有前瞻功能的分词器、高级搜索突出显示、从搜索中排除内容、社交卡、Cookie 同意、链接内容选项卡、在搜索中提升页面、自定义警告图标。

出于合规要求，不使用评论系统，所以也省略了。

3.6. 添加百度统计

先在百度统计里创建添加站点，确定后会看到javascript代码，复制代码。在docs目录下新建js目录，并在docs/js目录里放置baidu-tongji.js，将复制的代码粘贴进来。最后在mkdocs.yml里新增如下配置:

extra_javascript:
    - 'js/baidu-tongji.js'

3.7. 网站底部的版权和备案信息

简单来说，网站底部的版权声明遵循的格式是：

Copyright + [dates] + [author/owner]
Copyright © 2013-2022 菜鸟教程  runoob.com All Rights Reserved. 备案号：闽ICP备15012807号-1

Copyright可以写成版权所有符号©，或者是单词“Copyright”的缩写“Copr”。日期为首次公开发表的年份，或者是首版发表至今的年份。版权拥有者的名称，可以为企业、团体、个人等。例子是菜鸟教程。

网站下方应该显示网站备案编号，并且编号指向工信部（beian.miit.gov.cn）。代码是

<a href="https://beian.miit.gov.cn/" target="_blank">您的备案号</a>

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩

  2. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩