markdown linting accessibility 风格指南 documentation

Markdown 检查指南:15 个常见问题及修复方法

查找并修复常见的 Markdown 问题,包括跳过标题、丢失图像替代文本、裸 URL、损坏的代码围栏、不一致的列表和格式错误的表格。

W
WordToMD 团队
·

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. 没有替代文本的图像

问题

![](architecture.png)

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

修复

![Request flow from the browser through the API gateway to the orders service](architecture.png)

描述图像提供的信息,而不仅仅是其外观。除非媒介很重要,否则避免使用“image of”之类的短语。

装饰图像是一个特例。当图像不传达信息时,“HTML”中的空替代文本可能是正确的,但“Markdown”渲染器和内容工作流程有所不同。如果图像纯粹是装饰性的,首先询问它是否属于技术文档。

linter Markdown带有空替代文本的 ¤T​​000¤ 图像。的 图片格式化工具 可以生成具有显式替代和可选标题的图像标记。

问题

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.

在采用延期之前,请回答三个问题:

  1. 哪个渲染器拥有最终输出?
  2. 内容稍后需要移至其他地方吗?
  3. 当扩展不受支持时,读者会看到什么?

保留可移植的 Markdown 基础,并尽可能在发布边缘添加平台语法。

实用的 Linting 工作流程

步骤 1:检查结构

将源代码粘贴到 Markdown 规范检查。首先修复错误,然后修复警告,然后修复信息一致性项目。自动检查应识别位置;他们不应该默默地重写意义。

步骤 2:标准化困难元素

使用专用工具进行机械清理:

与重写整个文件的广泛格式化程序相比,集中更改会产生更小、更易于查看的差异。

步骤 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”在未来的编辑中更加便携、易于访问和可靠。