Network101

Appearance

5. Markdown 最佳实践与常见问题 ​

"好的文档不仅内容重要，格式和规范同样关键。"

本章总结 Markdown 编写的最佳实践，并列出常见错误和解决方案，帮助你写出专业、可维护的文档。

5.1 通用最佳实践 ​

5.1.1 保持简洁 ​

Markdown 的设计哲学是"易读易写"。避免过度格式化：

markdown
# 好 👍
使用简洁的标题结构，清晰的段落。

# 不好 👎
过度使用粗体、斜体、颜色（如果支持）等。

5.1.2 一致性 ​

  • 统一使用一种列表标记（推荐 - 无序，数字有序）
  • 标题层级连续，不要跳级
  • 代码块语言标识符使用标准名称（如 javascript 而非 js）

5.1.3 可读性优先 ​

  • 每行长度控制在 80-100 字符以内（软换行）
  • 段落之间空一行
  • 复杂内容使用列表或表格，避免大段文字

5.1.4 语义化 ​

  • 使用正确的标题层级（H1 > H2 > H3...）
  • 用 > 表示引用，用 ** 表示强调
  • 表格用于结构化数据，而非布局

5.1.5 可访问性 ​

  • 图片必须提供替代文本（alt text）
  • 链接文字应描述目标内容，避免"点击这里"
  • 复杂图表提供文字说明

5.2 标题使用规范 ​

✅ 推荐 ​

markdown
# 项目文档

## 安装指南

### Windows 安装

####  prerequisites

- 内容...

❌ 避免 ​

markdown
# 文档

## 2.1 安装

### 2.1.1 Windows

#### 2.1.1.1 前置条件

- 跳级使用标题（从 H2 到 H4）
- 标题中包含编号（让 Markdown 自动编号）

5.3 代码块最佳实践 ​

指定语言 ​

markdown
```python
def hello():
    print("Hello World")

### 显示行号

某些平台支持：

    ```python linenums
    # 第一行
    # 第二行
    ```

### 高亮特定行

```markdown
```python hl_lines="2 4"
def func():
    print("Line 2")  # 高亮
    print("Line 3")
    print("Line 4")  # 高亮

### 代码块标题

某些解析器支持：

    ```json {title="package.json"}
    {
      "name": "my-app"
    }
    ```

## 5.4 表格最佳实践

### 对齐

- 短内容左对齐（默认）
- 数值右对齐（便于比较）
- 标题或居中内容居中对齐

### 可读性

```markdown
| 功能 | 状态 | 说明 |
|------|------|------|
| 登录 | ✅ 完成 | 支持邮箱密码登录 |
| 注册 | 🔄 进行中 | 短信验证功能待测试 |
| 找回密码 | ⏳ 待开始 | 计划下周开发 |

使用 Emoji 或符号增强可读性。

避免复杂表格 ​

Markdown 表格不支持跨行跨列。复杂表格应使用 HTML 或截图。

5.5 链接与图片 ​

内部链接 ​

使用相对路径，便于项目迁移：

markdown
[安装指南](./installation.md)  ✅
[https://example.com/installation](https://example.com/installation)  ❌

引用链接（长文档） ​

对于多次引用的链接，使用引用式：

markdown
更多信息请参考 [VitePress 文档][vp]。

[vp]: https://vitepress.dev/

图片优化 ​

  • 提供有意义的 alt 文本
  • 大图考虑压缩或使用懒加载
  • 本地图片路径正确，避免死链

5.6 常见问题与解决方案 ​

Q1: 标题下划线混乱？ ​

问题：某些解析器对 === 和 --- 支持不一致。

解决：统一使用 # 语法，避免下划线形式。

Q2: 列表项中的换行不生效？ ​

问题：Markdown 将单行视为一个列表项。

解决：列表项内换行需要缩进两个空格：

markdown
- 第一行
  第二行（缩进）

Q3: 表格单元格内换行？ ​

问题：Markdown 表格不支持直接换行。

解决：使用 HTML <br> 或拆分表格。

Q4: 代码块中的反引号不显示？ ​

问题：代码块内包含 ``` 导致提前结束。

解决：使用更多反引号包裹：

````python
def func():
    print("``` 这是代码块中的反引号")
````

Q5: 特殊字符被转义？ ​

问题：*、_ 等被解释为格式标记。

解决：使用反斜杠转义 \* 或使用代码块。

5.7 兼容性注意事项 ​

不同平台对 Markdown 扩展支持不同：

功能CommonMarkGitHubVitePressHugo
表格❌✅✅✅
任务列表❌✅✅✅
删除线❌✅✅✅
自动链接❌✅✅✅
脚注❌✅✅✅
数学公式❌⚠️ 需配置✅⚠️ 需配置

建议：

  • 核心文档遵循 CommonMark 标准
  • 扩展功能根据目标平台选择
  • 重要文档在目标平台预览效果

5.8 工具推荐 ​

编辑器 ​

  • VS Code + Markdown All in One 插件
  • Typora（所见即所得）
  • Obsidian（知识库管理）

预览工具 ​

  • 浏览器插件（如 Markdown Preview Plus）
  • 在线编辑器（如 StackEdit、Dillinger）

格式化工具 ​

  • Prettier：自动格式化 Markdown
  • markdownlint：检查语法错误

静态站点生成器 ​

  • VitePress（本项目使用）
  • Hugo
  • Hexo
  • Jekyll

5.9 检查清单 ​

在提交或发布 Markdown 文档前，检查：

  • [ ] 标题层级正确，无跳级
  • [ ] 所有链接有效（内部链接路径正确）
  • [ ] 图片有 alt 文本，路径正确
  • [ ] 代码块指定了语言
  • [ ] 表格对齐合理，内容完整
  • [ ] 无未转义的特殊字符
  • [ ] 文档在目标平台预览正常
  • [ ] 语法检查工具无警告

总结 ​

Markdown 的核心是"内容优先"。掌握基础语法后，通过实践积累经验，了解不同平台的差异，逐步形成自己的编写规范。记住：好的 Markdown 文档应该在任何环境下都清晰可读。

上一篇: 4. 列表、引用与分割线