SublimeText-Markdown/MarkdownEditing 插件中的 Markdown 语法检查功能详解

前言

Markdown 作为一种轻量级标记语言，因其简洁易用的特性广受欢迎。然而在实际写作过程中，我们难免会出现一些格式错误或不规范的写法。SublimeText-Markdown/MarkdownEditing 插件内置了强大的 Markdown 语法检查功能（Lint），能够帮助开发者快速发现并修正这些问题。

如何使用语法检查功能

在 Sublime Text 中打开 Markdown 文档后，可以通过以下两种方式启动语法检查：

1. 快捷键组合：Ctrl+Shift+M（Windows/Linux）或 ⌘+⇧+M（Mac）
2. 通过命令面板输入：MarkdownEditing: Markdown Lint

插件提供两种检查模式：

1. 内置语法检查：使用插件自带的检查规则对当前文档进行分析
2. 外部工具检查：调用外部 markdownlint 工具进行检查（需要额外安装）

语法检查规则详解

规则工作原理

每个检查规则都是一个继承自 mddef 的类，主要包含以下关键属性：

• flag：正则表达式匹配标志
• desc：规则描述信息
• locator：用于定位问题的正则表达式
• gid：正则匹配组ID（默认为0）
• finish：是否在匹配后停止继续扫描（默认为false）

每个规则类还必须实现 test 方法，用于对匹配到的内容进行进一步验证。

常见检查规则解析

标题相关规则

1. MD001：标题级别应逐级递增

   • 错误示例：# H1 后直接跟 ### H3
   • 正确示例：# H1 → ## H2 → ### H3

2. MD002：文档第一个标题应为一级标题

   • 错误示例：文档以 ## H2 开头
   • 正确示例：文档以 # H1 开头

3. MD003：标题风格应保持一致

   • 错误示例：混用 # ATX 和 Setext 风格标题
   • 正确示例：统一使用一种标题风格

列表相关规则

1. MD004：无序列表符号应保持一致

   • 错误示例：混用 *、+ 和 -
   • 正确示例：统一使用一种符号

2. MD005：同级列表项缩进应一致

   • 错误示例：同级列表项使用不同缩进
   • 正确示例：同级列表项保持相同缩进

3. MD006：顶级列表应从行首开始

   • 错误示例：缩进的顶级列表项
   • 正确示例：从行首开始的顶级列表项

其他常见规则

1. MD009：行尾不应有空格
2. MD010：禁止使用制表符
3. MD011：链接语法不应反转
4. MD012：禁止连续空行
5. MD013：行长度限制（默认关闭）

自定义检查规则

修改现有规则

1. 在 lint.py 中找到对应的规则类（如 md001）
2. 调整 locator 正则表达式以改变匹配范围
3. 修改 test 方法实现自定义验证逻辑

创建新规则

新建规则需要继承 mddef 类并实现必要属性和方法。以下是一个示例：

class custom_rule(mddef):
    flag = re.M
    desc = '自定义规则描述'
    locator = r'匹配模式正则表达式'

    def test(self, text, s, e):
        ret = {}
        # 自定义验证逻辑
        if is_problem(text[s:e]):
            ret[s] = '错误提示信息'
        return ret

最佳实践建议

1. 标题使用：

   • 保持标题级别逻辑性
   • 标题前后保留空行
   • 避免在标题结尾使用标点

2. 列表格式：

   • 统一使用一种列表符号
   • 保持一致的缩进
   • 有序列表建议从1开始编号

3. 代码可读性：

   • 控制行长（建议72-80字符）
   • 避免多余空格
   • 使用空格而非制表符

结语

SublimeText-Markdown/MarkdownEditing 的语法检查功能能有效提升 Markdown 文档的质量和一致性。通过理解这些规则的工作原理和配置方法，开发者可以更好地利用这一工具，也可以根据团队规范自定义检查规则。合理使用这些功能，将显著提高 Markdown 文档的可读性和可维护性。