mdoc文档编写模板¶

警告¶

警告，也称为*标注*，是包含侧面内容的绝佳选择，不会严重中断文档流程。Material for MkDocs 提供了几种不同类型的警告，并允许包含和嵌套任意内容。

1.配置警告¶

配置警告首先需要在mdoc.yml中启用相应的扩展

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

使用方法¶

一个警告块以!!!开头，后面跟一个用作类型限定的关键字。块的内容在下一行，缩进四个空格。

!!! note
    这是一个警告！他展示了警告内容的基础样式。

呈现样式：

使用带有自定义标题的告警¶

!!! note "带有自定义标题的告警"
    这是一个带有自定义标题的告警块。

呈现样式

设置一个可折叠的告警¶

当使用???开头而不是!!!开头创建告警块时，告警块将呈现折叠状态，在告警块右侧有一个切换按钮可以切换折叠状态。

??? note "这是一个带有折叠的告警"
    这是一个带有折叠的告警！

呈现样式

内联块样式的警告¶

警告可以以内联块的样式呈现。

​ 这是一个带有内联块样式的警告!

​ 这是一个带有内联块样式的警告。

!!! info inline end "内联块样式警告"

​    这是一个带有内联块样式的警告!

!!! info inline "内联块样式警告"

​    这是一个带有内联块样式的警告。

呈现样式

Mkdoc支持的警告样式¶

note 笔记

呈现样式：

warning 警告

呈现样式

failure

呈现样式

danger 危险

呈现样式

bug 漏洞

呈现样式

example 例子

呈现样式

quote 引用

呈现样式

代码块¶

代码块和实例是技术文档和项目文档的重要组成部分。

用法¶

代码块必须用包含三个反引号的两行单独代码进行包围。要为这些代码添加语法高亮，请在代码块开头直接添加语言简码。

import transorflow as tf

为代码块添加标题¶

可以使用title="<custom title>"在短代码后直接使用的选项将自定义标题添加到代码块，例如显示文件的名称：

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

带行号的代码块¶

1
2
3
4
5
6
7

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

突出显示特定行¶

hl_lines可以通过将行号传递给紧跟在语言短代码后面的参数来突出显示特定行。请注意，行数从 开始1，无论 linenums中指定的起始行号是多少

1
2
3
4
5
6
7

```py linenums="1" 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]
```

注释¶

lorem ipsum dolor sit amet, (1) consectetur adipiscing elit. { .annotate } //保留一行 1. I'm an annotation! (1) { .annotate } 1. I'm an annotation as well!!

这是一个注释，用来测试注释的写法. (1) 打开注释 { .annotate } //保留一行 1. 这是第一层的注释. (1) { .annotate } 1. 这是第二层的注释。

This is a annotations. (1) { .annotate } //保留一行 1. This is one.

内容标签¶

用法¶

分组代码块¶

代码块是需要进行分组的重要场景之一。

#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

#include <iostream>

int main(void){
    std::count << "Hello world!" << std::end;
}

#include <stdio.h>
int main(vodi){
    print("hello world!\n")
    return 0;
}

* 这是一个无序列表
* 这是一个无序列表
* 这是一个无序列表

1. 这是一个有序列表
2. 这是一个有序列表
3. 这是一个有序列表

8.3.0

心跳

内部版本

insiders- 1.2.3

默认

1.2.3

默认值已计算

默认值为空

元数据属性

多个实例

可选功能

1.2.3

实验

插件

1.2.3

Markdown扩展

1.2.3

必须值

定制

公共

1.2.3

在页面添加评论¶

<script src="https://giscus.app/client.js"
        data-repo="hanstack/hanstack.github.io"
        data-repo-id="MDEwOlJlcG9zaXRvcnkzNDkyOTQ4NDg="
        data-category="Announcements"
        data-category-id="DIC_kwDOFNHRAM4ChhnB"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

插入视频外链¶

使用B站的视频外链即可

插入音频外链¶

使用网易云外链