Markdownlint项目中的MD029规则：有序列表项前缀规范详解

Markdownlint项目中的MD029规则：有序列表项前缀规范详解

【免费下载链接】markdownlint A Node.js style checker and lint tool for Markdown/CommonMark files. 项目地址: https://gitcode.com/gh_mirrors/ma/markdownlint

规则概述

MD029是Markdownlint工具中针对有序列表前缀格式的检测规则，它确保文档中的有序列表遵循一致的编号方式。该规则可以帮助开发者维护Markdown文档的格式统一性，提升文档的可读性和专业性。

核心功能

MD029规则主要检查以下内容：

1. 有序列表是否以"1."或"0."开头
2. 列表项的编号是否按数字顺序递增
3. 列表项的编号格式是否保持一致

配置参数详解

该规则支持通过style参数进行灵活配置，可选值包括：

1. one模式

要求所有列表项都使用"1."作为前缀

1. 第一项
1. 第二项
1. 第三项

2. ordered模式

要求列表项前缀按数字顺序递增

1. 第一项
2. 第二项
3. 第三项

也支持以"0."开头的递增模式

0. 第一项
1. 第二项
2. 第三项

3. one_or_ordered模式（默认）

同时接受上述两种格式

1. 第一项
1. 第二项
1. 第三项

或

1. 第一项
2. 第二项
3. 第三项

4. zero模式

要求所有列表项都使用"0."作为前缀

0. 第一项
0. 第二项
0. 第三项

特殊格式支持

MD029规则还支持以下特殊格式：

1. 前导零格式：允许使用前导零来保持对齐

01. 项目一
02. 项目二
...
10. 项目十

2. 代码块中断处理：正确处理列表中的代码块中断情况

常见错误示例

以下是一个典型的违反MD029规则的例子：

1. 第一项
3. 第三项

这种编号不连续的情况会被所有style配置检测为错误。

代码块中断问题处理

当代码块出现在列表项之间且缩进不当时，会导致列表被"打断"：

1. 第一项

```text
代码块

1. 第二项

正确的做法是将代码块缩进，使其成为前一个列表项的一部分：
```markdown
1. 第一项

   ```text
   代码块

2. 仍然是第一项的内容

## 最佳实践建议

1. 在团队协作项目中，统一选择一种style配置并保持一致
2. 对于技术文档，推荐使用`ordered`模式，便于直接引用特定条目
3. 在需要强调条目独立性的场景，可以使用`one`模式
4. 处理长列表时，考虑使用前导零格式保持对齐美观

## 规则设计原理

MD029规则的制定基于以下考虑：
1. **可读性**：一致的列表格式使文档更易于阅读和理解
2. **可维护性**：统一的格式便于后续编辑和更新
3. **明确性**：清晰的编号有助于准确引用特定条目
4. **自动化处理**：标准化的格式便于工具处理和转换

通过遵循MD029规则，开发者可以确保Markdown文档中的有序列表始终保持专业和一致的格式。

【免费下载链接】markdownlint A Node.js style checker and lint tool for Markdown/CommonMark files. 项目地址: https://gitcode.com/gh_mirrors/ma/markdownlint