Markdown 最佳实践

掌握 Markdown 写作规范和 VitePress 特有的排版技巧，让你的文档更专业、更易维护。

写作原则

三大核心原则

1. 一致性 — 同一篇文档中使用统一的格式风格
2. 可读性 — 源码和渲染结果都应易于阅读
3. 可维护性 — 结构清晰，方便后续更新和协作

文档结构模板

推荐每篇文档遵循以下结构：

---
title: 页面标题
description: 页面描述（150 字符以内）
tags:
  - 标签1
  - 标签2
---

# 页面标题

简短的引言段落，1-2 句话概括本文内容。

## 基础概念

核心概念解释...

## 使用方法

具体操作步骤...

## 进阶用法

高级技巧和场景...

## 常见问题

FAQ...

## 相关链接

相关文档链接...

标题规范

层级规则

# 一级标题 — 文档标题（每篇仅一个）

## 二级标题 — 主要章节

### 三级标题 — 子章节

#### 四级标题 — 尽量避免，除非内容非常复杂

避免跳级

不要从 # 直接跳到 ###，标题层级必须连续。

标题命名技巧

推荐写法	不推荐写法	原因
## 安装 VitePress	## 安装	标题脱离上下文时应仍有意义
## 配置导航栏	## 导航栏的配置方法说明	简洁明了
## 常见问题	## FAQ问答专区	遵循惯例命名
## 快速开始	## 第1步 开始	不用编号

标题前的锚点

VitePress 自动为标题生成锚点，规则如下：

• ## 快速开始 → #快速开始
• ## API 参考 → #api-参考
• ## Vue 3 组件 → #vue-3-组件

自定义锚点：

## 快速开始 {#quick-start}

文本排版

中英文混排

<!-- ✅ 正确：中英文之间加空格 -->
使用 VitePress 创建文档网站

<!-- ❌ 错误：中英文之间无空格 -->
使用VitePress创建文档网站

标点符号

<!-- ✅ 正确：中文语境使用中文标点 -->
这是中文句子，使用中文逗号。

<!-- ✅ 正确：英文语境使用英文标点 -->
This is an English sentence, with English comma.

<!-- ❌ 错误：中文句子用英文标点 -->
这是中文句子,用英文逗号.

强调使用

**加粗**：用于关键词、重要概念
*斜体*：用于术语定义、引用说明
`代码`：用于命令、文件名、变量名
~~删除线~~：用于标记过时内容

何时使用加粗

• 首次引入的重要概念
• 需要特别注意的警告内容
• 操作步骤中的关键动作

不要过度使用加粗，否则会削弱强调效果。

代码块规范

必须指定语言

<!-- ✅ 正确 -->
```typescript
const greeting: string = 'Hello'
```

<!-- ❌ 错误：未指定语言 -->
```
const greeting = 'Hello'
```

语言标识对照

文件类型	语言标识
TypeScript	typescript 或 ts
JavaScript	javascript 或 js
Vue SFC	vue
CSS	css
HTML	html
Bash/Shell	bash 或 sh
JSON	json
YAML	yaml 或 yml
Markdown	markdown 或 md
纯文本	text
配置文件	toml、ini 等

代码注释规范

// ✅ 正确：注释解释"为什么"和"注意点"
// VitePress 要求 Node.js 18+，低于此版本会构建失败
const nodeVersion = process.version

// ❌ 错误：注释重复代码含义
// 获取 node 版本
const nodeVersion = process.version

代码长度控制

• 单个代码块不超过 50 行
• 超过时考虑拆分为多个代码块或使用折叠容器
• 只展示关键部分，用 // ... 省略无关代码

::: details 查看完整代码
较长的代码放在折叠容器中...
:::

链接规范

链接文本要有描述性

<!-- ✅ 正确 -->
查看 [VitePress 官方文档](https://vitepress.dev) 了解更多

<!-- ❌ 错误 -->
点击 [这里](https://vitepress.dev) 了解更多

内部链接使用相对路径

<!-- ✅ 正确 -->
了解更多 [导航配置](/basics/navbar)

<!-- ❌ 错误：使用绝对 URL -->
了解更多 [导航配置](https://example.com/basics/navbar)

链接检查清单

• [ ] 内部链接路径正确（无 .md 后缀）
• [ ] 外部链接可访问
• [ ] 链接文本有描述性
• [ ] 不使用"点击这里"作为链接文本

表格规范

何时使用表格

• 对比不同选项的参数
• 列举配置字段
• 展示简短的映射关系

表格最佳实践

<!-- ✅ 正确：有表头，列对齐，内容简洁 -->
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| title | string | - | 页面标题 |
| layout | string | 'doc' | 页面布局 |

<!-- ❌ 错误：内容过长，不易阅读 -->
| 属性 | 说明 |
|------|------|
| title | 这个属性用于设置页面的标题，它会显示在浏览器标签页上，同时也会作为 SEO 的标题使用 |

对齐方式

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 默认 | 适合状态 | 适合数值 |

容器使用技巧

选择合适的容器类型

容器	使用场景	示例
tip	有用的建议、技巧	快捷键、优化方法
info	补充信息、说明	版本要求、兼容性
warning	需要注意的事项	废弃 API、潜在问题
danger	严重警告、风险	数据丢失、安全风险
details	可折叠的补充内容	完整代码、扩展阅读

容器嵌套

避免在容器中嵌套另一个容器。如果需要复杂排版，考虑使用自定义组件。

图片规范

基础写法

<!-- ✅ 正确：有 alt 文本 -->
![VitePress 配置界面截图](/images/guide/config-panel.png)

<!-- ❌ 错误：无 alt 文本 -->
![](/images/1.png)

暗色模式适配

<picture>
  <source srcset="/images/dark/logo-dark.png" media="(prefers-color-scheme: dark)">
  <img src="/images/logo.png" alt="Logo">
</picture>

图片尺寸提示

![配置界面](/images/config-panel.png =800x)

Frontmatter 最佳实践

必填字段

---
title: 页面标题          # 必填
description: 页面描述     # 必填，150 字符以内
---

推荐字段

---
title: 页面标题
description: 页面描述
author: 作者名
date: 2026-04-11
updated: 2026-04-11
difficulty: Beginner | Intermediate | Advanced
tags:
  - 标签1
  - 标签2
prev:
  text: 上一页标题
  link: /path/to/prev
next:
  text: 下一页标题
  link: /path/to/next
---

标签规范

• 技术专有名词首字母大写：VitePress、Vue、TypeScript
• 通用概念使用中文：配置、部署、优化
• 中英文混合加空格：API 文档

常见陷阱

1. 列表缩进错误

<!-- ✅ 正确：2 空格缩进 -->
- 项目一
  - 子项目 1.1
  - 子项目 1.2

<!-- ❌ 错误：4 空格缩进（VitePress 中可能渲染为代码块） -->
- 项目一
    - 子项目 1.1

2. 代码块嵌套

使用不同数量的反引号：

````markdown
```typescript
const config = {}
```
````

3. 特殊字符转义

<!-- 需要转义的字符 -->
\<angle brackets\>
\*not italic\*
\`not code\`

4. HTML 和 Markdown 混用

<!-- ✅ 正确：HTML 块级元素前后留空行 -->
<div class="custom">

Markdown 内容

</div>

<!-- ❌ 错误：HTML 标签紧接 Markdown -->
<div class="custom">
Markdown 内容
</div>

检查清单

每次提交文档前检查：

• [ ] Frontmatter 包含 title 和 description
• [ ] 标题层级连续，无跳级
• [ ] 中英文之间有空格
• [ ] 代码块指定了语言类型
• [ ] 链接文本有描述性
• [ ] 图片有 alt 文本
• [ ] 表格有表头行
• [ ] 容器类型选择恰当
• [ ] 无拼写和语法错误

相关链接

• Markdown 扩展语法 — VitePress 支持的 Markdown 扩展
• 自定义容器语法 — 容器类型和用法
• Frontmatter 配置 — 页面元数据配置
• SEO 优化 — 搜索引擎优化技巧