跳到主要内容

Markdown 语法概要

文档脑图​

下面通过左右对比的方式展示 Markdown 语法和实际效果

备注

有些语法只适用于 Docusaurus 及扩展

基础语法​

标题​

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

强调​

*斜体文本*
_斜体文本_

**粗体文本**
__粗体文本__

***粗斜体文本***
___粗斜体文本___

~~删除线文本~~

列表​

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

1. 第一步
2. 第二步
   1. 子步骤 2.1
   2. 子步骤 2.2
3. 第三步

- [x] 已完成任务
- [ ] 未完成任务
- [ ] 另一个未完成任务

链接和图片​

[链接文本](https://www.example.com)
[带标题的链接](https://www.example.com "链接标题")

![替代文本](https://via.placeholder.com/150)
![带标题的图片](https://via.placeholder.com/150 "图片标题")

引用​

> 这是一段引用文本
> 
> 这是引用的第二段
> > 这是嵌套引用

代码​

  • 使用 ``` 标记行内代码
  • 使用三个反引号创建代码块
  • 使用showLineNumbers显示行号
  • 使用highlight-next-line高亮单行
  • 使用highlight-start和highlight-end高亮多行
  • 使用title指定代码块标题
```javascript showLineNumbers title="示例代码"
const greeting = "Hello, World!";
console.log(greeting);

// 单行高亮
// highlight-next-line
console.log("This line is highlighted.");

// 多行高亮
// highlight-start
console.log("This line is highlighted.");
console.log("This line is also highlighted.");
// highlight-end
```

表格​

| 表头 1   | 表头 2   | 表头 3   |
| -------- | -------- | -------- |
| 单元格 1 | 单元格 2 | 单元格 3 |
| 单元格 4 | 单元格 5 | 单元格 6 |

Mermaid​

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Markmap 脑图​

Markmap 是 Markdown 生态中的脑图渲染工具，它直接使用标题、列表、链接、强调等 Markdown 语法描述层级结构。不过它不是 Markdown 的默认能力，需要编辑器、文档站点或插件接入 Markmap 渲染支持后，才能把 markmap 代码块或对应内容显示成脑图

常用写法：

  1. 根节点：通常使用一级标题 # 作为脑图中心主题
  2. 分支节点：使用二级、三级标题或列表缩进表达层级
  3. 内容增强：可以使用 **加粗**、`代码`、[链接](https://example.com) 等 Markdown 语法

基础脑图​

```markmap
# 学习计划

## 前端
- HTML
- CSS
- JavaScript

## 后端
- Go
- 数据库
- API 设计

## 工程化
- Git
- CI/CD
- 自动化测试
```

带 Markdown 元素的脑图​

```markmap
# 文档写作流程

## 准备
- 明确**目标读者**
- 收集参考链接
  - [Markdown Features](https://docusaurus.io/zh-CN/docs/markdown-features)
  - [Markmap](https://markmap.js.org/)

## 编写
- 用 `#`、`##`、`###` 划分结构
- 用列表拆分要点
- 用代码块展示示例

## 检查
- 内容是否完整
- 层级是否清晰
- 示例是否可渲染
```

文章摘要​

这是文章摘要
<!--truncate-->
这是文章正文

提示框​

:::note[备注]
这是一个备注框
:::

:::tip[提示]
这是一个提示框
:::

:::info[信息]
这是一个信息框
:::

:::caution[警告]
这是一个警告框
:::

:::danger[危险]
这是一个危险框
:::

高级用法​

Tab支持​

通过 <Tabs> 组件实现，每个标签页使用 <TabItem> 定义，相关参数：

  • value 和 label 属性分别指定标签页的标识和显示文本
  • default 属性指定默认选中的标签页

示例如下：

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

<Tabs>
  <TabItem value="tab1" label="Tab 1">
    这是Tab 1
  </TabItem>
  <TabItem value="tab2" label="Tab 2" default={true}>
    这是Tab 2
  </TabItem>
  <TabItem value="tab3" label="Tab 3">
    这是Tab 3
  </TabItem>
</Tabs>

效果预览：

这是Tab 2

折叠代码块​

自定义组件CodeBlock实现，通过在代码块元信息里添加 collapse 启用底部“展开更多/收起”按钮。基础示例（默认阈值，10 行）：

```bash title="安装步骤" collapse
echo 1
echo 2
echo 3
echo 4
echo 5
echo 6
echo 7
echo 8
echo 9
echo 10
echo 11
echo 12
```

自定义参数示例：

```tsx title="Example.tsx" collapse collapsedLines=2 labelMore="展开更多" labelLess="收起" maxHeight=80
export function Example(){
  // long code ...
}
```

可选参数说明：

  • collapsedLines=2：按行数估算折叠高度（默认 10 行）
  • maxHeight=80：直接用像素控制折叠高度
  • labelMore="展开更多"、labelLess="收起"：自定义按钮文案

注意：

  • 只有当内容高度超过阈值时才会显示“展开更多/收起”的按钮
  • 未加 collapse 的代码块保持默认样式与行为

最佳实践​

  1. 使用适当的标题层级
  2. 保持列表格式一致
  3. 为图片添加有意义的替代文本
  4. 使用代码块时指定语言
  5. 合理使用提示框和标签页
  6. 保持文档结构清晰

注意事项​

  • Markdown 文件需要以 .md 或 .mdx 结尾
  • 文件开头需要包含 frontmatter（使用 --- 包裹）
  • 图片建议使用相对路径
  • 代码块建议指定语言以获得语法高亮
  • 表格建议使用对齐语法

更多内容请参考Markdown Features

最后于 更新