跳到主要内容

文档编写规范

目录​

Front Matter 元数据​

每个文档文件顶部应包含 YAML front matter，用于配置文档的元数据：

---
id: doc-id                          # 文档唯一标识符（可选，默认为文件名）
title: 文档标题                      # 页面标题
sidebar_label: 侧边栏显示名称         # 侧边栏中显示的文本（可选）
sidebar_position: 1                 # 侧边栏中的排序位置（数字越小越靠前）
description: 文档描述                # SEO 描述
keywords:                           # SEO 关键词
  - 关键词1
  - 关键词2
tags: [标签1, 标签2]                # 文档标签
hide_title: false                   # 是否隐藏标题
hide_table_of_contents: false       # 是否隐藏目录
---

常用 Front Matter 字段说明​

字段说明示例
sidebar_position控制文档在侧边栏中的顺序sidebar_position: 2
sidebar_label自定义侧边栏显示文本sidebar_label: '快速开始'
title页面标题（会显示在浏览器标签）title: 新手指南
description页面描述（用于 SEO）description: 如何快速上手
tags文档分类标签tags: [教程, 入门]
draft标记为草稿（开发环境可见）draft: true
unlisted不在侧边栏显示但可访问unlisted: true

Markdown 基础语法​

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

**粗体文本**
*斜体文本*
~~删除线~~

[链接文本](https://example.com)
[内部链接](./other-doc.md)

![图片描述](/img/image.png)

代码块​

使用三个反引号包裹代码，并指定语言以启用语法高亮：

```javascript
function hello() {
  console.log('Hello, world!');
}
```

```python
def hello():
    print("Hello, world!")
```

支持的特性：

  • 添加标题：markdown ```js title="example.js"
  • 高亮行：markdown ```js {1,3-5}
  • 显示行号：markdown ```js showLineNumbers

告示框（Admonitions）​

用于突出显示重要信息：

:::note
这是一个普通提示。
:::

:::tip
这是一个小技巧。
:::

:::info
这是一条信息。
:::

:::warning
这是一个警告。
:::

:::danger
这是一个危险提示。
:::

自定义标题：

:::tip[自定义标题]
这里是内容。
:::

选项卡（Tabs）​

用于展示多种选择或多语言代码示例：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="js" label="JavaScript">
    ```js
    console.log('Hello');
    ```
  </TabItem>
  <TabItem value="py" label="Python">
    ```python
    print('Hello')
    ```
  </TabItem>
</Tabs>

图片处理​

<!-- 基础图片 -->
![图片描述](/img/screenshot.png)

<!-- 带链接的图片 -->
[![/screenshot.png)](https://example.com)

<!-- 使用相对路径 -->
![图片描述](./assets/image.png)

链接​

<!-- 外部链接 -->
[Docusaurus 官网](https://docusaurus.io)

<!-- 文档内部链接 -->
[查看新手指南](./新手指南/新手指南入口.md)
[相对路径](../功能文档/功能文档入口.md)

<!-- 锚点链接 -->
[跳转到某个标题](#标题名称)

表格​

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

<!-- 对齐方式 -->
| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 内容   | 内容 | 内容   |

列表​

<!-- 无序列表 -->
- 项目1
- 项目2
  - 子项目2.1
  - 子项目2.2

<!-- 有序列表 -->
1. 第一步
2. 第二步
3. 第三步

<!-- 任务列表 -->
- [x] 已完成任务
- [ ] 未完成任务

参考资料​