Markdown格式校验工具

#!/bin/bash

# 目标目录
target_dir="md"

# 如果目标目录不存在，则创建它
if [ ! -d "$target_dir" ]; then
    mkdir "$target_dir"
fi

# 查找并复制 .md 文件，排除目标目录
find . -path "./$target_dir" -prune -o -name "*.md" -exec cp {} "$target_dir" \;

echo "所有 .md 文件已经被复制到 $target_dir 目录，排除了 $target_dir 目录本身。"

在 find 命令中使用 prune 选项。这将防止 find 命令在 md 目录中查找 .md 文件

有没有markdown的错误检测器？比如能分析出xxx#11这种问题

有的，有很多 Markdown 的错误检测器，通常我们称之为 Linter。这些工具可以帮助你分析和修正 Markdown 文件中的各种问题。

您提到的 [xxx#11](../file/12.png) 是一个非常好的例子，因为它涉及到两种不同层面的“错误”：

语法/逻辑错误：你可能想插入一张图片 ![alt text](../file/12.png)，但错误地使用了文本链接的语法 [link text](...)。这在语法上是合法的 Markdown，但可能不是你的真实意图。
链接有效性错误：../file/12.png 这个相对路径是否存在？如果文件不存在，就是一个“断开的链接 (Broken Link)”。

针对这些不同层面的问题，有不同类型的检测工具。下面我将它们分类介绍：

1. Markdown 语法和风格检查器 (Linter)

这类工具主要专注于检查 Markdown 的语法规范、格式和风格一致性，是目前最主流的检测器。

代表工具：`markdownlint`

这是最流行、最强大的 Markdown Linter，它有一套非常丰富的检查规则（例如：标题层级是否正确、列表格式是否混用、代码块是否指定语言等）。

如何使用？

编辑器插件 (强烈推荐)：
- VS Code: 在扩展市场搜索并安装 David Anson 开发的 markdownlint 插件。它会实时地在你的文档中用波浪线标出问题，并给出修正建议，非常直观。
命令行工具 (markdownlint-cli):
- 适合在项目中进行批量检查，或集成到自动化流程中。
- 安装 (需要 Node.js): npm install -g markdownlint-cli
- 使用: markdownlint your-file.md 或 markdownlint "**/*.md"

注意：对于你提到的 [text](image.png) 问题，标准的 markdownlint 可能不会 将其标记为错误，因为它在语法上是有效的。Linter 主要关心的是“格式是否规范”，而不是“你的意图是什么”。但它可以帮你发现大量的其他格式问题。

2. 链接有效性检查器 (Broken Link Checker)

这类工具专门用来检查你文档中的所有链接（包括内部文件路径和外部网址）是否有效。这能直接解决你例子中的第二类问题。

代表工具：

lychee (命令行工具, 推荐)：
- 一个用 Rust 编写的、速度极快的链接检查器。它可以检查本地文件路径和远程 URL。
- 安装和使用请参考其 GitHub 仓库。
- 命令示例: lychee "**/*.md"
Check Markdown Links (VS Code 插件)：
- 在 VS Code 中安装这个插件，它可以扫描当前文件或整个工作区，高亮显示所有无效的链接。
awesome_bot (常用于 CI/CD)：
- 一个常用于 GitHub Actions 的工具，可以在你每次提交代码时自动检查所有 Markdown 文件中的链接。

3. CI/CD 自动化集成 (最佳实践)

对于团队项目或开源项目，最佳实践是将语法检查和链接检查都集成到持续集成 (CI) 流程中（例如 GitHub Actions）。这样可以确保每次提交到代码库的文档都是高质量的。

示例：使用 GitHub Actions 同时进行语法和链接检查

你可以在你的项目根目录下创建 .github/workflows/markdown-check.yml 文件，内容如下：

name: Check Markdown

on: [push, pull_request]

jobs:
  markdown-lint-and-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run Markdown Linter
        # 使用社区提供的现成 Action 来运行 markdownlint
        uses: action-simonw/markdown-lint@v2
        with:
          args: '**/*.md' # 检查所有 markdown 文件

      - name: Run Link Checker
        # 使用社区提供的 lychee-action
        uses: lycheeverse/lychee-action@v1
        with:
          args: "--verbose --no-progress '**/*.md'"
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

这份配置会在每次 push 或 pull_request 时自动：

用 markdownlint 检查所有 Markdown 文件的语法和风格。
用 lychee 检查所有链接的有效性。
如果任何一个环节出错，CI 流程就会失败，从而提醒你修正。

总结

工具类型	推荐工具	主要解决的问题
语法/风格检查	`markdownlint` (VS Code 插件或命令行)	格式规范、语法正确性、风格一致性
链接有效性检查	`lychee` (命令行), `Check Markdown Links` (VS Code)	断开的链接、文件路径错误
自动化流程	GitHub Actions	在代码提交时自动执行以上两种检查

为了全面检测 Markdown 中的错误，建议采用组合拳：在编辑器中安装 markdownlint 插件进行实时反馈，并配置 CI/CD 流程来自动进行语法和链接的双重检查。

npm install -g markdownlint-cli

markdownlint “**/*.md”

https://github.com/celestiaorg/celestia-app/blob/main/.github/workflows/markdown-linter.yml

真实例子~

链接检查器Lychee的使用

Fast, async, stream-based link checker written in Rust. Finds broken URLs and mail addresses inside Markdown, HTML, reStructuredText, websites and more!

https://github.com/lycheeverse/lychee

自动修复:

如果有 markdownlint-cli2 (自动修复工具)

#npm install -g markdownlint-cli2
#markdownlint-cli2-fix “**/*.md”

MD013 - 行长度限制（每行不超过80字符）
MD004 - 无序列表样式一致（不能混用 * 和 -）
MD012 - 多个连续空行（最多只能有1个空行） —-> 这不算啥大毛病吧…
MD034 - 裸URL（URL需要用 <> 或 [] 包装） —-> 即在markdown里面直接写了链接
MD026 - 标题末尾标点符号（标题不能以句号结尾）
MD041 - 第一行标题（文件应以 # 开头）
MD039 - 链接文本空格（链接文本不能有多余空格）

https://www.npmjs.com/package/markdownlint?activeTab=readme

完整的:

完整答案

Markdownlint 总共有 58个规则，从 MD001 到 MD058。

主要分类：

标题规则: MD001, MD003, MD018-MD026, MD036, MD041, MD043
列表规则: MD004-MD007, MD029, MD030, MD032
空格规则: MD009-MD012, MD027-MD028
代码规则: MD031, MD037-MD038, MD040, MD046, MD048
链接规则: MD034, MD039, MD042, MD044-MD045, MD052-MD053
格式规则: MD013-MD014, MD033, MD035, MD047, MD049-MD051, MD054-MD058

完整的 Markdownlint 规则列表（MD001-MD058）

标题相关规则

MD001 - header-increment - 标题级别应该递增
MD003 - header-style - 标题样式一致性
MD018 - no-missing-space-atx - ATX标题需要空格
MD019 - no-multiple-space-atx - ATX标题不要多个空格
MD020 - no-missing-space-closed-atx - 闭合ATX标题需要空格
MD021 - no-multiple-space-closed-atx - 闭合ATX标题不要多个空格
MD022 - blanks-around-headers - 标题周围需要空行
MD023 - header-start-left - 标题必须左对齐
MD024 - no-duplicate-header - 不要重复标题
MD025 - single-h1 - 只能有一个H1标题
MD026 - no-trailing-punctuation - 标题末尾不要标点符号
MD036 - no-emphasis-as-header - 不要用强调作为标题
MD041 - first-line-h1 - 第一行应该是H1标题
MD043 - required-headers - 必需的标题

列表相关规则

MD004 - ul-style - 无序列表样式一致性
MD005 - list-indent - 列表缩进一致性
MD006 - ul-start-left - 无序列表项左对齐
MD007 - ul-indent - 无序列表缩进
MD029 - ol-prefix - 有序列表序号
MD030 - list-marker-space - 列表标记后的空格
MD032 - blanks-around-lists - 列表周围需要空行 (爽哥注: 看了下没有空行也没啥事啊)

空行和空格规则

MD009 - no-trailing-spaces - 行末不要空格
MD010 - no-hard-tabs - 不使用硬制表符
MD011 - no-reversed-links - 链接语法不要颠倒
MD012 - no-multiple-blanks - 不要多个连续空行
MD027 - no-multiple-space-blockquote - 块引用不要多个空格
MD028 - no-blanks-blockquote - 块引用内不要空行

代码相关规则

MD031 - blanks-around-fences - 代码块周围需要空行
MD037 - no-space-in-emphasis - 强调标记内不要空格
MD038 - no-space-in-code - 行内代码不要空格
MD040 - fenced-code-language - 代码块需要语言标识
MD046 - code-block-style - 代码块样式一致性
MD048 - code-fence-style - 代码围栏样式

链接相关规则

MD034 - no-bare-urls - 不要使用裸URL
MD039 - no-space-in-links - 链接文本中不要空格
MD042 - no-empty-links - 不要空链接
MD044 - proper-names - 专有名词大小写
MD045 - no-alt-text - 图片需要alt文本
MD052 - reference-links-images - 引用链接和图片
MD053 - link-image-reference-definitions - 链接和图片引用定义

格式和样式规则

MD013 - line-length - 行长度限制
MD014 - commands-show-output - 命令显示输出
MD033 - no-inline-html - 不使用内联HTML
MD035 - hr-style - 水平线样式一致性
MD047 - single-trailing-newline - 文件末尾单个换行符
MD049 - emphasis-style - 强调样式一致性
MD050 - strong-style - 粗体样式一致性
MD051 - link-fragments - 链接片段
MD054 - link-image-style - 链接和图片样式
MD055 - table-pipe-style - 表格管道样式
MD056 - table-column-count - 表格列数一致性
MD058 - blanks-around-tables - 表格周围需要空行

其他规则

MD002 - first-header-h1 - 第一个标题应该是H1
MD015 - no-missing-space-atx - ATX标题缺少空格
MD016 - no-multiple-space-atx - ATX标题多个空格
MD017 - no-multiple-space-closed-atx - 闭合ATX标题多个空格
MD057 - blanks-around-tables - 表格周围空行

常用配置文件模板

宽松配置（推荐）

{
  "MD013": false,
  "MD033": false,
  "MD041": false,
  "MD026": false,
  "MD036": false,
  "MD046": {"style": "fenced"}
}

严格配置

{
  "MD013": {"line_length": 100},
  "MD046": {"style": "fenced"},
  "MD040": true
}

你的项目推荐配置

根据你遇到的错误，建议使用：

{
  "MD013": false,
  "MD004": false,
  "MD012": false,
  "MD034": false,
  "MD026": false,
  "MD041": false,
  "MD039": false,
  "MD022": false,
  "MD031": false,
  "MD032": false,
  "MD040": false,
  "MD010": false,
  "MD053": false,
  "MD036": false,
  "MD024": false,
  "MD046": false
}

使用方法

# 创建配置文件
echo '配置内容' > .markdownlint.json

# 运行检查
markdownlint --ignore "CHANGELOG.md" "**/*.md"

总共有 58个规则（MD001-MD058），但实际使用中通常只需要关注其中的 20-30 个常用规则。

比较有价值的:

MD039 - no-space-in-links - 链接文本中不要空格

MD042 - no-empty-links - 不要空链接

MD053 - link-image-reference-definitions - 链接和图片引用定义

有时可能是有价值的:

MD024 - no-duplicate-header - 不要重复标题

MD046 code-block-style - 代码块样式一致性 —> 有时也比较有价值,但是可能误报会有很多

MD036 - no-emphasis-as-header - 不要用强调作为标题

可酌情处理:

MD040 - fenced-code-language - 代码块需要语言标识

原文链接: https://dashen.tech/2023/12/26/Markdown格式校验工具/

版权声明: 转载请注明出处.

清澄秋爽

苹果树下的思索者书写是对思维的缓存

Markdown格式校验工具

1. Markdown 语法和风格检查器 (Linter)

代表工具：`markdownlint`

2. 链接有效性检查器 (Broken Link Checker)

代表工具：

3. CI/CD 自动化集成 (最佳实践)

总结

如果有 markdownlint-cli2 (自动修复工具)

完整的 Markdownlint 规则列表（MD001-MD058）

标题相关规则

列表相关规则

空行和空格规则

代码相关规则

链接相关规则

格式和样式规则

其他规则

常用配置文件模板

宽松配置（推荐）

严格配置

你的项目推荐配置

使用方法

文章目录

1. Markdown 语法和风格检查器 (Linter)

代表工具：markdownlint

2. 链接有效性检查器 (Broken Link Checker)

代表工具：

3. CI/CD 自动化集成 (最佳实践)

总结

如果有 markdownlint-cli2 (自动修复工具)

完整的 Markdownlint 规则列表（MD001-MD058）

标题相关规则

列表相关规则

空行和空格规则

代码相关规则

链接相关规则

格式和样式规则

其他规则

常用配置文件模板

宽松配置（推荐）

严格配置

你的项目推荐配置

使用方法

文章目录

代表工具：`markdownlint`