第 10 章 最佳实践与工具链
本章覆盖：
| 主题 | 说明 |
|---|---|
| 写作风格 | 一致符号、对齐、空行规范 |
| 兼容性 | 不同方言差异处理 |
| 工具链 | 编辑器、预览、转换 |
| 自动化 | CI 校验、格式化、链接检查 |
| 排版细节 | 中英文混排、引号、空格 |
10.1 写作风格一致
10.1.1 统一列表符号
- 全文统一用
-、*或+中的一种 - 推荐用
-（与多数 linter 默认一致）
10.1.2 统一强调符号
- 斜体统一用
*x*（不用_x_） - 粗体统一用
**x** - 删除线统一用
~~x~~
10.1.3 围栏代码块统一用三反引号
- 不混用
```与~~~，除非需要嵌套 - 始终写语言标识：
```python、```bash
10.1.4 表格对齐
源码示例（列对齐用 :，列宽尽量对齐）：
| 名称 | 数量 | 单价 |
| :------- | :---: | -----: |
| 苹果 | 3 | 4.5 |
| 长名称 | 100 | 0.5 |渲染效果：表格整齐易读。
10.2 段落与空行规范
- 段落之间始终留一个空行
- 列表项之间如无必要不空行（保持紧凑）
- 代码块前后各留一空行
源码示例：
段落一。
```python
print("hi")
```
段落二。10.3 中英文混排排版
10.3.1 中英文之间加空格
源码：
使用 Markdown 编写文档，推荐配合 Hugo 使用。渲染效果：中英文之间有空格，便于阅读。
此为中文排版习惯（参考 pangu.js），非 Markdown 强制要求。
10.3.2 中文引号与英文引号
源码：
他说"Markdown 很好用"，并写了《Markdown 实战》一文。渲染效果：中文用全角引号，英文用半角引号。
10.4 兼容性处理
10.4.1 不同方言差异
| 语法 | CommonMark | GFM | Hugo Book |
|---|---|---|---|
| 表格 | 否 | 是 | 是 |
| 任务列表 | 否 | 是 | 是 |
| 删除线 | 否 | 是 | 是 |
| 脚注 | 否 | 否 | 是 |
高亮 ==x== |
否 | 否 | 视配置 |
| 定义列表 | 否 | 否 | 否 |
| Admonition | 否 | 否 | 视主题 |
10.4.2 兼容性策略
- 用最广方言（CommonMark + GFM）写作
- 不支持的语法用 HTML 兜底
- 引用目标方言文档，避免假设
10.5 工具链
10.5.1 编辑器
| 编辑器 | 特点 |
|---|---|
| VS Code | 内置预览、插件丰富（Prettier、markdownlint） |
| Typora | 即时渲染、所见即所得 |
| Obsidian | 双链笔记、本地存储 |
| Zettlr | 学术写作、Pandoc 集成 |
| MarkText | 开源所见即所得 |
10.5.2 预览与转换
| 工具 | 用途 |
|---|---|
| Pandoc | Markdown ↔ HTML/Word/PDF/EPUB |
| mdBook | 生成在线电子书 |
| MkDocs | 文档站点 |
| Docsify | 运行时渲染 |
| Hugo | 静态站点（本站使用） |
10.5.3 Linter 与格式化
| 工具 | 说明 |
|---|---|
| markdownlint | VS Code 插件，检查风格 |
| Prettier | 自动格式化 |
| remark-cli | 插件化处理 |
| markdown-link-check | 检查死链 |
10.6 自动化（CI）
10.6.1 GitHub Actions 检查链接
# .github/workflows/link-check.yml
name: Check Markdown Links
on: [push, pull_request]
jobs:
link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: gaurav-nelson/github-action-markdown-link-check@v110.6.2 格式化提交前钩子
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- repo: https://github.com/igorshubovych/markdownlint-cli
rev: v0.38.0
hooks:
- id: markdownlint10.7 SEO 友好
- 标题层级清晰：一篇文档一个 H1，下级 H2/H3 层层递进
- 段落首句包含关键字
- 代码块写语言标识（部分高亮器生成
class利于索引） - 图片务必写
alt - 链接文本描述目标，避免"点击这里"
- 外链适当加
rel="nofollow noopener"防权重流失
10.8 可访问性（a11y）
- 标题层级不跳级（H1 → H2 → H3）
- 图片
alt描述内容 - 链接文本可脱离上下文理解
- 表格使用
<th scope="col">或scope="row" - 颜色不作为唯一信息载体
10.9 性能
- 图片压缩、用 WebP / AVIF
- 代码块避免过长
- 避免 HTML 嵌入大量内联样式
- 静态站点启用 CDN 缓存
10.10 综合实例：一份规范文档模板
源码：
---
title: 文档标题
description: 一句话描述文档
---
# 文档标题
## 概述
一段正文，介绍文档目的。
## 安装
```bash
npm install pkg
```
## 使用
| 参数 | 类型 | 默认 | 说明 |
| :--- | :---: | :---: | :--- |
| name | string | - | 必填 |
| count | number | 0 | 可选 |
## FAQ
<details>
<summary>常见问题</summary>
解答内容。
</details>
## 参考
- [CommonMark 规范](https://spec.commonmark.org/current/)
- [GFM 规范](https://github.github.com/gfm/)10.11 小结
- 写作风格一致：统一符号、对齐、空行
- 中英文混排加空格，引号全/半角区分
- 用最广方言写作，不支持的语法用 HTML 兜底
- 编辑器选 VS Code / Typora；转换用 Pandoc
- CI 检查死链、格式化、lint
- SEO + a11y + 性能缺一不可