becheran/mlc

Markup Link Checker (mlc)

概述

Markup Link Checker (mlc) 是一个轻量级Docker镜像，专为验证标记语言文档中的链接有效性设计。支持Markdown、HTML等主流格式，可自动扫描内部锚点、相对路径链接及外部URL，识别死链接、无效引用和不可达资源，适用于文档维护、内容发布校验及自动化流程集成。

核心功能与特性

• 多格式兼容：支持Markdown、HTML等标记语言文档的链接检查。
• 全面链接验证：检查内部锚点（如#section）、相对路径及外部URL的有效性。
• 死链接检测：识别无法访问的外部URL、已失效资源链接和无效内部引用。
• 批量处理能力：支持单个文件或目录级别的批量文档扫描。
• 结构化报告：输出清晰的检查结果，标注问题链接位置及错误原因。
• 轻量级设计：基于精简基础镜像，启动快速且资源占用低。

使用场景与适用范围

• 文档维护：开源项目README、技术手册的链接质量日常检查。
• 内容发布校验：博客、知识库、帮助中心内容发布前的死链接筛查。
• CI/CD集成：作为自动化流程环节，在文档提交或构建时自动执行链接检查。
• 团队协作：确保多人协作编辑的文档中链接一致性与有效性。

使用方法

基本使用（Docker Run）

通过挂载本地文档目录运行容器，默认扫描指定路径下的所有支持格式文档：

bash
docker run --rm -v /本地文档路径:/docs mlc /docs

参数说明：

• -v /本地文档路径:/docs：将本地文档目录挂载至容器内/docs目录（mlc默认工作目录）。
• /docs：容器内待扫描的目标路径，可指定具体文件（如/docs/README.md）或目录。

自定义配置

支持通过命令行参数调整检查行为，常用参数包括：

• --exclude <pattern>：排除符合模式的文件/目录（如--exclude "node_modules/*"）。
• --follow-redirects：启用HTTP重定向跟随（默认禁用）。
• --timeout <seconds>：设置链接检查超时时间（默认10秒，如--timeout 20）。
• --output <file>：将结果输出至指定文件（如--output mlc-report.txt）。

示例：扫描单个Markdown文件并输出报告

bash
docker run --rm -v $(pwd):/docs mlc /docs/guide.md --follow-redirects --timeout 15 --output report.txt

CI/CD集成示例（GitHub Actions）

在自动化流程中集成链接检查：

yaml
jobs:
  link-validation:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run mlc
        run: docker run --rm -v $(pwd)/docs:/docs mlc /docs --output mlc-results.txt
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: link-check-report
          path: mlc-results.txt

注意事项

• 权限配置：确保挂载的本地目录对容器有读取权限，避免因权限不足导致扫描失败。
• 网络环境：外部URL检查受网络影响，建议在稳定网络环境下运行，或通过--exclude跳过受限域名。
• 大型文档集：扫描包含大量链接的目录时，可通过--timeout延长超时时间，确保检查完整性。