Markdown¶

Markdown 有很多的方言，mkdocs 支持了基本的 Markdown 语法，而material for mkdocs 支持更多的语法。 基本的 Markdown 语法参考这里,本文只记录一些特殊的 Markdown 语法和mkdocs的拓展语法。 为了通用性，书写风格尽可能使用 GitHub 的风格。

• 特殊 Markdown
• Admonititions
• Annotations
• Buttons
• Code blocks
• Content tabs
• Data tables
• Diagrams
• Footnotes
• Grids
• Icons, Emojis
• Images
• Lists
• Math
• Tooltips

特殊 Markdown¶

折叠内容¶

<details>
  <summary>点击查看 python 代码</summary>

  ```python
  def greet(name):
    return f"hello {name}"

  print(greet("world))
  ```

</details>

def greet(name):
  return f"hello {name}"

print(greet("world))

如果需要默认展开，在 details 标签中添加 open 属性即可。

<details open>
  <summary>点击查看 python 代码</summary>

  ```python
  def greet(name):
    return f"hello {name}"

  print(greet("world))
  ```

</details>

def greet(name):
  return f"hello {name}"

print(greet("world))

这个代码在 material for mkdocs 中的渲染效果是 Admonition 的效果

HTML 标签波浪线问题¶

因为 Markdown 的规范中默认是不应该有 html 标签，但是如果要在 markdown 中使用 html 标签，需要在项目根目录下创建一个.markdownlint.json 文件。

{
  "MD033": false
}

脚注¶

代码

这是一个[脚注][1] 效果

[1]: https://www.example.com

效果

这是一个脚注 效果

admonitions¶

改用 GitHub 风格的 callout¶

为了保证文档尽可能的兼容多其他平台，还是使用 GitHub 风格的 callout 吧。 基本的写法

> [!note]
> this is callout

效果

需要使用插件 markdown-callouts

基本提醒¶

!!! 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
• abstract
• info
• tip
• success
• question
• warning
• failure
• danger
• bug
• example

嵌套提醒¶

!!! note "Outer 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 "Inner 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.

默认折叠的提醒¶

就是把感叹号替换成问号

??? 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 在左侧显示提醒框

!!! info inline end "Lorem ipsum"

    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"

    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.

给代码添加标题¶

代码

```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]
```

这个效果只能在 material for mkdocs 中使用。

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. I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown.

剥离注释

# (1)!

1. Look ma, less line noise!

添加行号

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]

高亮行

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]

tab¶

#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;
}

print("Hello world!")

根据其他内容分组

嵌入式 tab

* 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

表格¶

对齐列

导入 csv 文件

...

{{ read_csv('./data.csv') }}

...

图表¶

flowchat

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

序列图

sequenceDiagram
  autonumber
  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!

状态图

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 --> [*]

类图

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()
  }

实体关系图

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

脚注¶

Lorem ipsum[^1] 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.

格式化¶

Text can be {--deleted--} and replacement text {++added++}. This can also be combined into {one~>a 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.

==}

高亮文本

• This was marked
• This was inserted
• This was deleted

角标

• H₂O
• A^TA

键盘按键

Ctrl+Alt+Del

图像¶

``` title = "image"

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

```

添加图像名称

公式¶

行内公式

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)\).

tooltips¶

Hover me

添加到链接

Hover me

添加到图标

添加缩写

The HTML specification is maintained by the W3C.

_[HTML]: Hyper Text Markup Language _[W3C]: World Wide Web Consortium