编写文档¶

本指南介绍如何使用 Material for MkDocs 编写优秀的文档。

基础 Markdown 语法¶

标题¶

使用 # 符号创建标题：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

文本格式¶

**粗体文本**
*斜体文本*
~~删除线~~
`行内代码`

效果：

粗体文本
斜体文本
~~删除线~~
行内代码

列表¶

无序列表：

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

有序列表：

1. 第一项
2. 第二项
3. 第三项

链接和图片¶

[链接文本](https://example.com)
![图片描述](path/to/image.png)

高级功能¶

提示框（Admonitions）¶

Material 支持多种类型的提示框：

笔记

这是一个笔记提示框。

摘要

这是一个摘要提示框。

信息

这是一个信息提示框。

提示

这是一个提示框。

成功

这是一个成功提示框。

问题

这是一个问题提示框。

警告

这是一个警告提示框。

失败

这是一个失败提示框。

危险

这是一个危险提示框。

Bug

这是一个 Bug 提示框。

示例

这是一个示例提示框。

引用

这是一个引用提示框。

可折叠提示框¶

使用 ??? 创建可折叠的提示框：

点击展开

这个内容默认是折叠的。

代码块¶

基础代码块¶

```python
def hello_world():
    print("Hello, World!")
```

带行号的代码块¶

```python linenums="1"
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

效果：

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

高亮特定行¶

```python hl_lines="2 3"
def example():
    # 这行会被高亮
    # 这行也会被高亮
    return True
```

效果：

def example():
    # 这行会被高亮
    # 这行也会被高亮
    return True

代码注释¶

```python
def process_data(data):  # (1)!
    result = transform(data)  # (2)!
    return result
```

1. 处理输入数据
2. 转换数据格式

选项卡¶

使用选项卡组织不同的内容：

PythonJavaScriptJava

def greet(name):
    return f"Hello, {name}!"

function greet(name) {
    return `Hello, ${name}!`;
}

public String greet(String name) {
    return "Hello, " + name + "!";
}

表格¶

基础表格¶

功能	描述	状态
搜索	全文搜索	✅
导航	多级导航	✅
主题	深色模式	✅

对齐方式¶

左对齐	居中对齐	右对齐
左	中	右
Left	Center	Right

任务列表¶

已完成的任务
另一个已完成的任务
待完成的任务
另一个待完成的任务

脚注¶

使用脚注添加额外信息¹。

键盘按键¶

使用 ++key++ 语法显示键盘按键：

Ctrl+Alt+Del

Cmd+Space

图标和表情¶

Material 支持大量图标：

Material 图标
Font Awesome 图标
Octicons 图标
Simple Icons

表情符号：

数学公式¶

行内公式：\(E = mc^2\)

块级公式：

\[ \frac{n!}{k!(n-k)!} = \binom{n}{k} \]

Mermaid 图表¶

流程图¶

graph LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E

序列图¶

sequenceDiagram
    participant A as 用户
    participant B as 服务器
    A->>B: 发送请求
    B->>B: 处理请求
    B-->>A: 返回响应

类图¶

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    class Cat {
        +meow()
    }
    Animal <|-- Dog
    Animal <|-- Cat

最佳实践¶

文档结构¶

清晰的层次结构 - 使用合适的标题级别
简洁的段落 - 每段专注于一个主题
使用列表 - 让信息更易于扫描
添加示例 - 用代码示例说明概念

写作技巧¶

写作建议

使用主动语态
保持简洁明了
使用具体的例子
添加视觉元素（图表、代码块等）
定期更新内容

代码示例¶

提供完整的、可运行的代码
添加注释解释关键部分
使用语法高亮
考虑添加多语言示例

下一步¶

了解样式定制
查看 Material 主题文档

这是脚注的内容。 ↩