MkDocs 加强语法¶

预计阅读时长 : 14 分钟

要想写出美观、漂亮、炫酷炸裂的文档，仅仅掌握基本的 Markdown 语法是远远不够的。以下介绍的加强语法，都是 Material for MkDocs 中的专属特性，其中还有一些需要通过另外的第三方插件实现。

因此，本文展现的效果，仅限于在我个人专属的 Material for MkDocs insider 版本中使用，其他版本的 MkDocs 的支持程度各不相同。

emoji & Icons¶

提升文章的趣味性，可以在 Markdown 文本中插入 emoji & Icons ⧉ 。目前主要支持 emoji、Material Design 和 Fontawesome 三种类型，还可以使用 CSS 样式来增加颜色和动效。

• // 使用更合适的开心表情
• // 使用图标来代表程序员
• // 使用图标来代表笔记本电脑

Link¶

链接的富文本展现也是提升文档可读性的重要手段，Link-Preview ⧉ 可以在 Markdown 文本中插入富文本链接，用于展示链接的图标、标题、描述等信息。

Keyboard¶

写教程是不可避免要使用快捷键的，Keys ⧉ 可以在 Markdown 文本中插入键盘按键样式，这对于提升教程文档的可读性非常有帮助。

• Ctrl+Alt+My Special Key
• Cmd+Alt+Ü

Admonitions¶

对于需要特别强调的大块内容，可以通过 Admonitions ⧉ 在插入一些醒目的提示框。

Anotations¶

Annotations ⧉ 的主要使用场景主要是为文本添加注释，而又不影响阅读体验。

1
2
3
4
5
6
7
8

!!! note annotate "Phasellus posuere in sem ut cursus (1)"

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

1.  :man_raising_hand: I'm an annotation!
2.  :woman_raising_hand: I'm an annotation as well!

1. I'm an annotation!
2. I'm an annotation as well!

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.

Definition Lists¶

Definition lists ⧉ 可以在文本中插入词汇定义列表，相对于脚注和缩写会更加直接明了。

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.

Content tabs¶

Content tabs ⧉ 可以在文本中插入用标签切换的内容块，用于在同一个块中平行展示多个内容。

Tables¶

Tables ⧉ 可以在文本中插入数据表格，用于展示数据。通过添加自定义的 CSS 样式和 JS 脚本，可以实现排序、对齐等多种增强功能。

Markdown 的表格默认不支持合并单元格，事实上合并之后也会影响增删改查以及排序等操作。但在特定的场景下，对于那些不经常修改的表格，我们也会有合并单元格美化展示效果的需求。

通过 Neoteroi - Spantable ⧉ 的扩展支持，我们可以实现如下的效果。

Buttons¶

Buttons ⧉ 可以在文本中插入按钮，用于直观的引导用户进行下一步操作。

Send

Badges¶

Badges ⧉ 可以在文本中插入各种样式的勋章，用于展示例如版本号、包依赖等信息。

[Link badge equivalent | example.com]

Grids¶

Grids ⧉ 可以在 Markdown 文本中插入网格布局，用于展示多个内容块。

如果有图片导航的需求，则可以使用 Neoteroi Cards ⧉，样式会更加美观。

Zeus

Lorem ipsum dolor sit amet.

Athena

Lorem ipsum dolor sit amet.

Poseidon

Lorem ipsum dolor sit amet.

Artemis

Lorem ipsum dolor sit amet.

Ares

Lorem ipsum dolor sit amet.

Nike

Lorem ipsum dolor sit amet.

Image¶

由于 HTML 中的图片语法不支持居中对齐，为了实现这个效果，我们需要使用 img2figv2 ⧉ 来将其自动嵌套在一个 <figure> 标签中实现默认对齐效果。不过，如果设定了 width 参数，那么就只能设定左对齐或者右对齐了。。

Excalidraw¶

Excalidraw ⧉ 是一个非常强大的在线绘图工具，可以用来绘制各种图表和流程图。最特别的是，Excalidraw 支持手写体，看起来非常漂亮。

Video¶

使用 <video> 标签可以在文本中插入本地视频文件或者网络视频文件，但是由于视频的体积较大会严重消耗流量，因此一般不会直接插入本地视频，而是通过插入第三方视频网站的链接来实现同样的效果。

1
2
3
4
5
6
7
8

<video controls>
  <source
    src="https://addon-docs.ankiweb.net/img/autocomplete.mp4"
    type="video/mp4"
    title="Title"
  />
  您的浏览器不支持 HTML5 视频标签。
</video>

对于中文视频，我们一般都会放到 Bilibili 上。为了提升嵌入视频的体验，我们需要按照 关于博客园内嵌入 bilibili 视频的优化 ⧉ 中的教程对官方提供的代码进行一些优化。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<div style="position: relative; padding: 30% 45%;">
  <iframe
    style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;"
    src="https://player.bilibili.com/player.html?cid=1325568478&aid=920673650&page=1&as_wide=1&high_quality=1&danmaku=0"
    frameborder="no"
    scrolling="no"
    allowfullscreen="allowfullscreen"
    sandbox="allow-top-navigation allow-same-origin allow-forms allow-scripts"
  ></iframe>
</div>

ProgressBar¶

ProgressBar ⧉ 可以在 Markdown 文本中插入进度条，用于展示工作进度。

Flowchart¶

Mermaid ⧉ 可以在文本中插入 Mermaid 语法支持的图表，用于展示流程图 ⧉、序列图 ⧉、类图 ⧉、用户旅程 ⧉、Git 图表 ⧉等多种和技术开发相关的图表。

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

目前 >10+ 版本的 Mermaid 样式在 MkDocs for Material 中已经默认支持，再也不需要通过 MkDocs-Mermaid2 ⧉ 插件实现的。

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

Mindmap¶

Markmap ⧉ 是一个简洁的思维导图插件，可以在文本中插入思维导图。

类似的思维导图，在 Mermaid Mindmap ⧉ 中也可以实现，但是 Mermaid 的思维导图语法略显复杂，不如 Markmap 的思维导图语法直观。

mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

Gantt¶

Mermaid 还支持 Gantt 图表 ⧉，可以直观的展现项目的进展。

gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d
    Functionality added                 :milestone, 2014-01-25, 0d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

Neoteroi 也有 Gantt 图表 ⧉的样式，两者各有特定，可以根据需要选择。

Timeline¶

Timeline 也是一种非常漂亮的图表，Mermaid Timeline ⧉ 的样式很简洁。

timeline
        title MermaidChart 2023 Timeline
        section 2023 Q1 <br> Release Personal Tier
          Buttet 1 : sub-point 1a : sub-point 1b
               : sub-point 1c
          Bullet 2 : sub-point 2a : sub-point 2b
        section 2023 Q2 <br> Release XYZ Tier
          Buttet 3 : sub-point <br> 3a : sub-point 3b
               : sub-point 3c
          Bullet 4 : sub-point 4a : sub-point 4b

同样的，Neoteroi 也有 Timeline 图表 ⧉。两者一个纵向显示，一个横向显示，配合起来可以满足多种类型的需求。