Skip to main content

Markdown 编写规范

约定​

文件与目录​

  • 使用 kebab-case 命名（小写英文 + 连字符），如 code-review-guide.md。禁止空格、下划线、中文文件名。
  • 目录同上，按功能组织，如 30.areas/finance/。
  • 编码 UTF-8，换行 LF，后缀统一 .md。

Frontmatter​

每个文件顶部用 YAML Frontmatter 声明元数据：

---
title: 文档标题
tags: [tag1, tag2]
date: 2026-06-21
---
字段必填说明
title是文档标题，与正文 H1 一致
tags推荐用于分类检索
date视情况时间敏感内容标注日期

中文排版​

  • 中英文之间加空格：「使用 React 开发」而非「使用React开发」。
  • 中文与数字之间加空格：「第 3 个版本」而非「第3个版本」。
  • 使用中文标点：逗号 ， 句号 。 引号 「」，不混用英文标点。
  • 专有名词正确大小写：GitHub、TypeScript、Docusaurus、Obsidian。
  • 加粗和行内代码不紧贴标点：「使用 React 开发」而非「使用React开发」。

一、基础语法速查​

1.1 标题​

语法：

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

规范：

  • ✅ 一文档一 H1：# 只用一次作为主标题。
  • ✅ 逐级不跳级：# → ## → ### → #### 依次递进。
  • ✅ 层级不超过 4 级：深于 #### 时拆分文档或改用列表。
  • ✅ 标题简洁：5~15 字，陈述句，不含标点结尾。
  • ❌ 跳级标题：# 直接到 ###，跳过 ##。
  • ❌ 不用标题做字号变化。

1.2 文本强调​

语法：

**加粗**
*倾斜*
***加粗倾斜***
`行内代码`

示例：加粗　倾斜　加粗倾斜　行内代码

规范：

  • ✅ 加粗用于强调关键词。
  • ❌ 整段加粗，分不清重点。
  • ❌ 不用标题做字号变化。

1.3 引用​

语法：

> 单层引用
>> 嵌套引用

规范：

  • ✅ 用于引用或补充说明，引用中可嵌套列表、代码等。
  • ❌ 不要用引用代替正文排版。

1.4 分割线与空行​

语法：

---

规范：

  • ✅ 章节间视觉分隔。
  • ✅ 段落间空一行：不同段落之间恰好一个空行。
  • ✅ 标题前后：标题前空一行，标题后紧跟内容。
  • ✅ 代码块 / 列表 / 表格：前后各空一行，与正文明确分隔。
  • ❌ 不连续使用多条分割线；不连续出现 3 行以上空行。
  • ⚠️ 文件顶部的 --- 是 YAML Frontmatter 分隔符，正文中使用需前后留空行。

1.5 图片​

语法：

![替代文本](图片路径)

规范：

  • ✅ 必填 alt text：![架构图](./arch.png)，不省略为 ![](./arch.png)。
  • ✅ 本地优先：图片放同级目录或统一 assets/ 目录。
  • ✅ 截图配说明：每张截图下方用简短文字说明关键信息。
  • ✅ 截图用 PNG，示意图优先 SVG。
  • ❌ 不要用外部 URL 作为主图源。

1.6 超链接​

语法：

[链接文字](URL)
[链接文字](#锚点)
<https://example.com>
<email@example.com>

规范：

  • ✅ 描述性文字：[API 接口文档](./api.md)，链接文字应描述目标内容。
  • ✅ 内部链接：用相对路径 ./other-file.md 或 ../folder/file.md。
  • ✅ 外部链接：重要引用标注访问日期。
  • ❌ 无意义文字：[点击这里](./api.md)、[链接]。

1.7 列表​

语法：

- 无序项
1. 有序项
  - 嵌套（两个空格缩进）
- [ ] 任务项
- [x] 已完成

规范：

  • ✅ 同层级统一符号；嵌套用两个空格缩进。
  • ❌ 不要混用 - + *。
  • ❌ 普通列表和任务列表不要混在同一层级。

1.8 表格​

语法：

| 左对齐 | 居中 | 右对齐 |
|--------|:----:|-------:|
| 内容   | 内容 | 内容   |

规范：

  • ✅ 必须有表头，用 --- 行分隔。
  • ✅ 冒号控制对齐：:--- 左、:---: 中、---: 右。
  • ❌ 缺表头：数据行直接拼接，无 --- 分隔行。
  • ❌ 列数不宜超过 5 列。

1.9 代码​

语法：

行内：`code`
代码块：
```language
代码内容
```

规范：

  • ✅ 必须标注语言： ```typescript，禁止裸 ```。
  • ✅ 代码前写引导语：一句话说明代码用途或上下文。
  • ✅ 行内代码用于变量名、文件名、命令，如 config.json、npm install。
  • ❌ 截图代替代码：贴 IDE 截图展示代码，应改用代码块。
  • ❌ 大段代码无说明：直接贴长代码块，前无引导语。
  • ❌ 超过 40 行考虑精简或外链完整文件。

1.10 注释​

语法：

<!-- 注释内容，渲染时不可见 -->

1.11 转义字符​

语法：

\*  \_  \#  \[  \]  \(  \)  \`  \~

用反斜杠 \ 让特殊字符按字面显示，而非被解析为 Markdown 语法。

示例：*不是斜体*　# 不是标题

规范：

  • ✅ 需要原样显示 * _ # [] 等符号时加 \ 转义。
  • ❌ 代码块内不需要转义，内部内容原样输出。

二、进阶语法​

2.1 脚注​

语法：

正文中有脚注引用[^1]。

[^1]: 这是脚注内容。

规范：

  • ✅ 用于补充说明、引用出处。
  • ⚠️ 部分平台渲染方式不同，确认目标平台支持。

2.2 删除线​

语法：

~~删除的文本~~

示例：这个功能已废弃

规范：

  • ✅ 标记已废弃或不再适用的内容。
  • ❌ 不要大段使用删除线。

2.3 Emoji​

语法：

:smile:  :warning:  :+1:  :tada:

示例：😄 ⚠️ 👍 🎉

规范：

  • ✅ 适度使用，增强表达。
  • ❌ 不要连续大量使用。
  • ⚠️ 短码渲染依赖平台支持，不确定时用 Unicode：😊 ⚠️ 👍 🎉

2.4 HTML 内嵌​

用于 Markdown 原生语法不支持的排版需求。

常用标签：

<kbd>Ctrl</kbd> + <kbd>C</kbd>
<mark>高亮文字</mark>
<sup>上标</sup> <sub>下标</sub>

<details>
<summary>点击展开详情</summary>
折叠的内容在这里。
</details>

规范：

  • ✅ 仅在 Markdown 无法满足需求时使用。
  • ❌ 避免复杂 HTML 结构，影响可读性和跨平台兼容性。

2.5 数学公式​

语法：

行内：$E = mc^2$
块级：$$
\sum_{i=1}^{n} x_i
$$

规范：

  • ⚠️ 需要渲染器支持 LaTeX（MathJax、KaTeX）。
  • ✅ 公式前后留空格。

2.6 定义列表​

语法（HTML 方式）：

<dl>
<dt>术语</dt>
<dd>术语的定义说明。</dd>
</dl>

规范：

  • ⚠️ 标准 Markdown 不支持定义列表，需用 HTML。
  • ✅ 适用于术语表、API 参数说明。

2.7 缩写​

语法（HTML 方式）：

<abbr title="HyperText Markup Language">HTML</abbr>

规范：

  • ✅ 首次出现的缩写给出全称说明。
  • ⚠️ <abbr> 在部分平台无视觉提示，建议首次出现直接用「全称（缩写）」的写法。

附录 A：Docusaurus 特性语法​

以下语法仅在 Docusaurus 环境下生效。

Admonitions（提示框）​

:::tip 提示
这是一条提示信息。
:::

:::warning 警告
这是一条警告信息。
:::

:::danger 危险
这是一条危险警告。
:::

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

:::note 备注
这是一条备注。
:::

代码块标题​

```typescript title="src/greet.ts"
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

代码行高亮​

```typescript {2,4-6} showLineNumbers
function greet(name: string): string {
  // highlight-next-line
  console.log('entering greet');
  if (!name) {
    throw new Error('Name is required');
  }
  return `Hello, ${name}!`;
}
```

{2,4-6} 高亮指定行，showLineNumbers 显示行号。// highlight-next-line 和 // highlight-start / // highlight-end 是注释式高亮标记。

Tabs 组件​

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

<Tabs>
<TabItem value="npm" label="npm">

```bash
npm install
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn install
```

</TabItem>
</Tabs>

附录 B：Obsidian 特性语法​

以下语法仅在 Obsidian 环境下生效。

Wiki-links（内部链接）​

[[笔记名称]]
[[笔记名称|显示文本]]
[[文件夹/笔记名称]]

块引用​

[[笔记名称#^block-id]]
[[笔记名称#标题文本]]

^block-id 引用笔记中的特定段落（需在目标段落后添加 ^block-id 标识），#标题 引用指定标题段落。

Callout（标注块）​

> [!note] 标题
> 内容

> [!warning] 注意
> 警告内容

> [!info] 信息
> 信息内容

> [!tip] 提示
> 提示内容

> [!danger] 危险
> 危险内容

嵌入​

![[图片.png]]
![[笔记名称]]      （嵌入整个笔记）
![[音频.mp3]]

标签​

#tag-name
#folder/tag-name