Advanced Usage for markdown

Here are some advanced usage in markdown specifically in Mkdocs¹. Below are some demonstrations.

A simple demo 的部分是上文 markdown 代码的实际展示。

更多设置请参考官方文档：Official Docs

Admonitions（文本高亮框）

你可以在自己的文档中创建高亮文本框。

Markdown

!!! Note "A simple demo"
    ??? note "this is a note"
        This is a note.
    ??? abstract "this is an abstract"
        This is an abstract.
    ??? info "this is an info"
        This is an info.
    ??? tip "this is a tip"
        This is a tip.
    ??? success "this is a success"
        This is a success.
    ??? question "this is a question"
        This is a question.
    ??? warning "this is a warning"
        This is a warning.
    ??? failure "this is a failure"
        This is a failure.
    ??? danger "this is a danger"
        This is a danger.
    ??? bug "this is a bug"
        This is a bug.
    ??? example "this is an example"
        This is an example.
    ??? quote "this is a quote"
        This is a quote.

Here are all the admonitions

this is a note

This is a note.

this is an abstract

This is an abstract.

this is an info

This is an info.

this is a tip

This is a tip.

this is a success

This is a success.

this is a question

This is a question.

this is a warning

This is a warning.

this is a failure

This is a failure.

this is a danger

This is a danger.

this is a bug

This is a bug.

this is an example

This is an example.

this is a quote

This is a quote.

具体使用方法详见：Admonitions³

关于 Admonitions 的缩进

Mkdocs 的 Admonitions 功能对缩进有严格要求:

!!! 这一行的内容要和你当前所在的内容缩进一致
!!! 下面的内容要在它的基础上再向右缩进4个空格

对于 !!! 的嵌套使用，若编译出问题，请严格检查你的缩进

Fonts

对于有颜色的字体，可以使用 HTML 块包裹：

HTML

<!-- 不同大小和颜色的字体 -->
<span style="font-size:24px; color:#015c43;font-family: 'Microsoft YaHei', '微软雅黑', sans-serif; font-weight: bold;">大号深绿色字体</span>

<span style="font-size:16px; color:#e67e22;">中号橙色字体</span>这是正常字体。

<!-- 居中显示 -->
<p align="center">
  <span style="font-size:20px; color:#023c31;">居中深绿色字体</span>
</p>

<!-- 不居中显示 -->
<span style="font-size:18px; color:#c0392b;">左对齐红色字体</span>

A simple demo

大号深绿色字体

中号橙色字体这是正常字体。

居中深绿色字体

左对齐红色字体

对于更加复杂的字体设置，可以在官方教程中找到支持。

Buttons

你可以在自己的文档中创建按钮²，实现链接跳转。

Markdown

[Go to SAI!](https://soai.sjtu.edu.cn/){ .md-button }

[See the fonts](#fonts){ .md-button .md-button--primary }

A simple demo

Go to SAI!

See the fonts

可视注释

Markdown

你好，这里是 SAI，(1) 我是 SAI 的一名本科生。{ .annotate }

1. :smile: Wow, it is SAIer!

A simple demo

你好，这里是 SAI, (1) 我是 SAI 的一名本科生。

Wow, it is SAIer!

注意空格和使用英文括号。

你也可以在代码的注释中添加 annotations！

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]
# (1)

Is this correct?

代码块

代码块行数高亮

Markdown

```py title="bubble_sort.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]

a simple demo

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]

像 OI-wiki 一样，也可以整合多个代码块。

Markdown

=== "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;
    }
    ```

a simple demo

CC++

C

#include <stdio.h>

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

C++

#include <iostream>

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

Mermaid 流程图

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

链接：

窗格

可以在文章的目录上使用，获得更好的视觉体验

HTML

<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`mkdocs-material`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

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

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

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

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

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

    [:octicons-arrow-right-24: License](#)

</div>

A simple demo

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

符号和表情

本站支持 FontAwesome⁴，一款广受欢迎的免费开源图标库，提供超过 2,000+ 个可缩放矢量图标。

Markdown

:smile:
:fontawesome-solid-file-zipper:{ .saic }

如果需要添加新的 css，请发起PR。

数学公式

环境配置完成，可正常使用。

\[ \cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k},\quad x\in\mathbb R. \]

markdown 书写排版规范

建议参考：