Markdown 是允许的。存在结构错误的文档仍可能会呈现,这使得这些错误很容易被忽略,直到表格损坏、标题从导航中消失或图像对屏幕阅读器用户来说变得毫无意义。
Markdown linting 是在发布之前检查源文本结构、可访问性和一致性问题的过程。从 Markdown 规范检查 捕获跳过的标题级别、丢失的图像替代文本、裸露的 URL、未标记或未封闭的代码围栏以及尾随空白。然后使用本指南中的手动检查表进行更广泛的编辑审查。
Linting 并不是强制执行任意偏好。有用的规则应该防止真正的读取、渲染、维护或可访问性问题。
快速发布前清单
| 检查 | 为什么它很重要 | 自动还是手动? |
|---|---|---|
| 标题层次结构 | 保留文档结构 | 短绒 |
| 图片替代文本 | 使图像无需视觉即可理解 | 短绒 |
| 描述性链接 | 改进可访问性和扫描 | Linter + 手动审查 |
| 封闭式代码围栏 | 防止页面的其余部分成为代码 | 短绒 |
| 代码语言标签 | 启用有用的语法突出显示 | 短绒 |
| 尾随空格 | 避免隐形的、特定于方言的行为 | 短绒 |
| 一个清晰的页面标题 | 保持页面目的明确 | 人工审核 |
| 一致的列表 | 防止嵌套破损 | 人工审核 |
| 有效表格 | 保持柱结构完整 | 人工审核 |
| 独特的标题 | 防止重复锚混淆 | 人工审核 |
| 便携式HTML 使用 | 避免特定于渲染器的故障 | 人工审核 |
| 可读段落 | 提高理解力 | 人工审核 |
将代表性文档粘贴到 linter 中,运行检查,修复报告的行,然后在实际发布系统中预览完整页面。
1. 跳过标题级别
问题
# Deployment Guide
### Configure credentials
文档从 H1 跳转到 H3。当字体大小是唯一可见的信号时,它看起来可能是可以接受的,但结构轮廓缺少一个层次。
修复
# Deployment Guide
## Configure credentials
使用标题来描述层次结构,而不是选择视觉大小。如果“配置凭据”确实属于缺失的部分,请添加该部分:
# Deployment Guide
## Preparation
### Configure credentials
的 Markdown 规范检查 报告跳转超过一级的标题。
2. 多个或缺失的 H1 标题
一页通常应有一个清晰的标题。一些文档系统从前面的内容生成 H1,而其他文档系统则期望它在“Markdown”正文中。了解您的网站使用哪种约定。
来源不明确
# Installation
# Configuration
清晰来源
# Product setup
## Installation
## Configuration
如果您的网站模板呈现 title: Product setup 作为页面 H1,正文可以改为以 H2 开头。规则不是“每个 Markdown 文件必须恰好包含一个 #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. 仅用于强调的标题
此源创建了不必要的大纲条目:
#### Important!
如果文本没有介绍某个部分,请使用散文或适当的标注:
**Important:** Back up the database before continuing.
标题应该帮助读者导航。装饰性标题会使目录变得嘈杂,并降低辅助导航的实用性。
4. 没有替代文本的图像
问题

该图像没有替代文本。看不到它的读者不会收到任何解释,浏览损坏或禁用图像的人也无法确定其目的。
修复

描述图像提供的信息,而不仅仅是其外观。除非媒介很重要,否则避免使用“image of”之类的短语。
装饰图像是一个特例。当图像不传达信息时,“HTML”中的空替代文本可能是正确的,但“Markdown”渲染器和内容工作流程有所不同。如果图像纯粹是装饰性的,首先询问它是否属于技术文档。
linter Markdown带有空替代文本的 ¤T000¤ 图像。的 图片格式化工具 可以生成具有显式替代和可选标题的图像标记。
5. 薄弱或裸链接
问题
Visit https://example.com/docs/setup for more information.
裸露的 URL 很难扫描,而且大声朗读时可能会令人不愉快。通用链接文本也好不了多少:
[Click here](https://example.com/docs/setup).
修复
Read the [service setup guide](https://example.com/docs/setup).
描述性链接告诉读者他们将打开什么。当它们被提取到链接列表中时也仍然有意义。
linter 识别出许多裸露的 http:// and https:// URL,但仍需要编辑审查来判断链接文本是否有用。
6. 未封闭的代码围栏
问题
```javascript
const status = 'ready';
## Next section
如果没有关闭围栏,渲染器可能会将页面的其余部分视为代码。
修复
```javascript
const status = 'ready';
```
## Next section
未封闭的栅栏可能会破坏原本有效的文档的大部分。linter 报告不匹配栅栏开始的行。
7. 没有语言标识符的代码围栏
不太有用
```
npm run build
```
更好
```bash
npm run build
```
语言标识符支持语法突出显示并传达读者正在看到的内容类型。使用通用标识符,例如 javascript, typescript, json, html, css, bash, powershell, yaml,或 markdown.
不要仅仅为了获得颜色而添加不准确的语言。对于非结构化输出,请使用 text 当目的地识别它时。
8. 列表缩进不一致
问题
- Install dependencies
- Production packages
* Development packages
- Optional tools
混合制表符、空格和标记很难查看,并且可能会在不同级别上呈现。
修复
- Install dependencies
- Production packages
- Development packages
- Optional tools
为项目选择一致的缩进宽度。空格的确切数量可能取决于“Markdown”方言和列表内容,但一致性至关重要。
使用 嵌套列表格式化工具 在最终审核之前规范混合项目符号、编号、制表符和缩进。
9. 手动输入数字序列
长编号列表的维护成本很高:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
许多Markdown渲染器允许每个项目使用 1. 同时仍然显示有序序列:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
这减少了源差异中的重新编号噪音。然而,当说明提到“步骤 3”时,明确编号的来源更容易讨论。选择一种项目惯例并一致地应用它。
不要组合键入的数字、有序列表标记和段落文本。编辑嵌套步骤后确认渲染结果。
10. 格式错误的表格
问题
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
分隔符和数据行不包含相同的逻辑列数。
修复
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
还要检查单元格内的未转义管道字符:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
的 Markdown 表格格式化工具 有助于暴露不均匀的行并产生对齐的源。要直观地创建新表,请使用 Markdown 表生成器.
11. 重复标题和锚点冲突
文档可以合法地重复可见标题,例如“示例”,但自动生成的锚点 ID 可能会变成 #examples, #examples-1,以及 #examples-2。确切的规则因渲染器而异。
重复的标题使手动链接变得脆弱:
- [API examples](#examples)
- [CLI examples](#examples)
更喜欢描述性标题:
## API examples
## CLI examples
然后生成一个目录 Markdown TOC 发生器 并验证目标平台中的锚点。
12. 尾随空白
行尾的空格是不可见的。在某些“Markdown”方言中,两个尾随空格会创建硬换行符,这意味着意外的编辑器操作可能会更改呈现。
linter 报告尾随空白,以便您可以确定它是否是故意的。最好用空行来分隔段落。如果确实需要严格的换行,请一致地记录并应用项目所选择的约定。
编辑器通常可以在保存时自动删除尾随空格,但请检查这不会更改旧内容中的有意换行符。
13. 降低可移植性的原始HTML
Markdown 通常允许嵌入 HTML:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
该块可能在一个网站上有效,但在其他地方会被转义、清理或设置错误的样式。当可以表达相同含义时,首选便携式Markdown:
> **Warning:** Restarting the service ends active sessions.
故意使用 HTML 来表示 Markdown 无法表达的功能,例如受控的图像尺寸或支持的 <details> 块。保留内容必须呈现的目的地列表并测试每个目的地。
的 标注生成器 可以为 GitHub、Obsidian 和 MkDocs 生成特定于平台的语法。
14. 段落过长且易读性差
Markdown在结构上可能是有效的,但仍然难以阅读。包含多项决定、警告和程序的文本墙应该重新组织。
使用:
- 一个主要思想的短段落;
- 导航描述性标题;
- 平行项目列表;
- 真正可比字段的表格;
- 用于文字输入和输出的代码块;
- 少量重要异常的标注。
不要把每句话都变成子弹。当项目具有相同的语法和概念角色时,列表效果最佳。
使用 字数统计与阅读时间 检查段落数、标题数和阅读长度,但将统计数据视为信号而不是目标。
15. 没有兼容性计划的渲染器特定语法
GitHub 任务列表、Obsidian wiki 链接、MkDocs 警告、脚注、定义列表和前言都很有用,但并非所有地方都支持它们。
例如:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
在采用延期之前,请回答三个问题:
- 哪个渲染器拥有最终输出?
- 内容稍后需要移至其他地方吗?
- 当扩展不受支持时,读者会看到什么?
保留可移植的 Markdown 基础,并尽可能在发布边缘添加平台语法。
实用的 Linting 工作流程
步骤 1:检查结构
将源代码粘贴到 Markdown 规范检查。首先修复错误,然后修复警告,然后修复信息一致性项目。自动检查应识别位置;他们不应该默默地重写意义。
步骤 2:标准化困难元素
使用专用工具进行机械清理:
- 嵌套列表格式化工具 用于缩进;
- Markdown 表格格式化工具 用于管道表;
- 图片格式化工具 用于图像标记;
- 目录生成器 用于航向锚。
与重写整个文件的广泛格式化程序相比,集中更改会产生更小、更易于查看的差异。
步骤 3:预览文档
打开源代码 Markdown 编辑 并将 Markdown 与渲染输出进行比较。检查:
- 标题和目录;
- 列表和任务列表;
- 窄屏幕上的表格;
- 图像和链接;
- 代码块和内联代码;
- 标注或原始HTML。
步骤 4:测试真实目的地
通用预览无法重现每个渲染器。在发布之前,在GitHub、Obsidian、GitLab、MkDocs 或实际文档站点中打开文件。
步骤 5:回顾含义,而不仅仅是语法
没有 linter 可以确定程序是否安全、指向预期策略的链接或图像描述是否传达重要结论。人工审阅者应确认准确性、完整性、语气和受众契合度。
团队风格指南建议
一个简短的书面约定比几十个不言而喻的偏好更有效。定义:
- 页面标题是否位于前面内容或“Markdown”正文;
- 允许的航向进展;
- 列表缩进和有序列表样式;
- 代码围栏语言要求;
- 如何审查图像和替代文本;
- 表复杂性限制;
- 允许HTML和平台扩展;
- 最大线长度(如果团队使用一条线);
- 如何检查链接;
- linter 规则阻止发布。
从防止真正缺陷的规则开始。仅当团队了解其解决的问题时才添加规则。
FAQ
有效的Markdown 是否可以自动访问?
否。有效的语法仍然可能包含空的替代文本、模糊的链接、令人困惑的标题、难以访问的图表和糟糕的阅读顺序。可访问性需要结构和编辑审查。
Markdown Linter 会重写我的文档吗?
WordToMD linter 报告行号问题。它不会默默地重写源代码,因此您可以保留对每次更正的控制。
为什么 linter 报告一个裸 URL?
描述性链接文本更易于扫描,对辅助技术更有用。将 URL 替换为有意义的标签,除非文字地址是读者需要的信息。
未标记的代码围栏总是错误的吗?
并不总是如此,但正确的语言标识符通常可以提高清晰度和语法突出显示。使用 text 用于在受支持时进行纯输出,而不是分配不准确的编程语言。
所有项目都应该使用相同的 linting 规则吗?
否。“GitHub”、“README”、“Obsidian”保管库、“API”参考和发布站点具有不同的约定。共享一组核心结构和可访问性规则,然后添加特定于目的地的检查。
linting 可以代替校对吗?
否。linter 检测模式。它无法可靠地验证技术真相、论证质量、用户意图或句子在上下文中是否可以理解。
结论
好 Markdown 不仅仅是恰好渲染的源。它具有清晰的轮廓、有意义的链接、可访问的图像、完整的代码围栏、一致的列表、有效的表格以及与其发布平台的明确关系。
运行 Markdown 规范检查 对于快速结构检查,请使用 Markdown 编辑 用于视觉审查,并仅在使源代码更易于维护的地方应用集中格式化程序。结果是“Markdown”在未来的编辑中更加便携、易于访问和可靠。