跳转至

MkDocs 加强语法

预计阅读时长 : 9 分钟

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

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

emoji & Icons

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

  • 😄

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

Keyboard

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

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

Admonitions

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

看不懂的法语~

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.

Anotations

Annotations ⧉ 的主要使用场景主要是在代码块中插入注释,可以进一步提升代码的展示效果。

代码注释
1
2
3
theme:
  features:
    - content.code.annotate # (1)
  1. 🙋‍♂️ I'm a code annotation! I can contain code, formatted
    text
    , images, ... basically anything that can be written in Markdown.

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.

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.

Grids

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

  • Set up in 5 minutes


    Install mkdocs-material with pip and get up
    and running in minutes

    Getting started

  • It's just Markdown


    Focus on your content and generate a responsive and searchable static site

    Reference

  • Made to measure


    Change the colors, fonts, language, icons, logo and more with a few lines

    Customization

  • Open Source, MIT


    Material for MkDocs is licensed under MIT and available on [GitHub]

    License

如果有图片导航的需求,则可以使用 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.

Buttons

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

Send

Badges

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


[Link badge equivalent | example.com]

Code blocks

Code blocks ⧉ 在基本语法的基础上增加了大量的特性,可以支持标题、行号、高亮、复制、注释等多种功能。

Python
1
2
3
4
5
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i): #(1)
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
  1. 第二层循环和条件判断

Content tabs

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

  • Sed sagittis eleifend rutrum
  • Donec vitae suscipit est
  • Nulla tempor lobortis orci
  1. Sed sagittis eleifend rutrum
  2. Donec vitae suscipit est
  3. Nulla tempor lobortis orci

Tables

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

Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource

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

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

合并表格示例
Italy 40 20
Men Women Men Women
78 82 77 81
Poland 40 20
Men Women Men Women
78 82 77 81

Image

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

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
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 图表 ⧉的样式,两者各有特定,可以根据需要选择。

2022
Q1
Q2
March 2022
April 2022
May 2022
W9W10W11W12W13W14W15W16W17W18W19W20W21W22

Creation Phase

Sketching
Design Building
Refining

Feedback Phase

Presenting
Revisions

Delivery Phase

Final delivery

Timeline

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

timeline
        title MermaidChart 2023 Timeline
        section 2023 Q1 
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
Release XYZ Tier Buttet 3 : sub-point
3a : sub-point 3b : sub-point 3c Bullet 4 : sub-point 4a : sub-point 4b

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

Launch

2022-Q1

First implementation.

New features

2022-Q2

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

More features!

2022-Q3

Lorem ipsum dolor sit amet.

Bugs!

2022-Q4

Lorem ipsum dolor sit amet.

ProgressBar

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


85%


100%

Video

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

本地视频嵌入代码
<video src="../../media/video/test.mp4" controls title="Title"></video>

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