maneesh-kumar-thakur/MD-Files-Connector
GitHub: maneesh-kumar-thakur/MD-Files-Connector
一款用于检查并修复项目中未从根目录 README 链接的 Markdown 孤立文件的自动化工具。
Stars: 2 | Forks: 1
# 📋 MD 文件连接器
[](https://github.com/maneesh-kumar-thakur/MD-Files-Connector/actions/workflows/ci.yml)
[](https://github.com/marketplace/actions/md-files-connector)
[](https://github.com/maneesh-kumar-thakur/MD-Files-Connector/releases/latest)
[](https://www.python.org/)
[](LICENSE)
[](#-隐私--安全)
一个轻量级的命令行工具兼 GitHub Action，可扫描项目中的 Markdown 文件，并告知哪些文件**已在根 `README.md` 中被引用**——以及哪些文件对读者来说是**孤立且不可见的**。
每个 `.md` 文件——包括子目录中嵌套的 `README.md` 文件——都必须从**根 `README.md`** 链接，才能被视为已覆盖。这确保了你的根 README 是所有项目文档的单一事实来源。
## 为什么需要它？
随着项目增长，文档也会积累。`CONTRIBUTING.md`、`ARCHITIBUTURE.md`、`docs/API.md`——它们被写出来后就被遗忘了。这个工具能让你的 README 保持诚实。
## 功能特性
- 🔍 递归扫描整个项目中的 `.md` 文件
- 📖 仅检查**根 `README.md`** 的覆盖情况（严格模式）
- ✅ 将每个文件分类为**已链接**或**孤立**
- 📊 输出带有覆盖率统计的终端仪表盘
- 📄 生成包含完整分析的 `MD_REPORT.md` 文件
- 🤖 作为 **GitHub Action** 在每次推送或 PR 时运行
- 🔧 交互式修复菜单——可自动将孤立文件链接到你的 README
- 💡 无需安装，无需配置——一个文件，一条命令
- 🌐 **语言无关**——无论技术栈如何，适用于任何项目
## 🔒 隐私与安全
- **数据不出你的机器。** 工具在本地读取文件路径和 Markdown 内容以构建覆盖报告。不会在你的项目之外收集、传输或存储任何数据。
- **不读取或复制代码。** 仅扫描 `.md` 文件——你的源代码、配置和机密信息绝不会被触及。
- **无网络调用。** CLI 完全离线运行。GitHub Action 仅使用 GitHub 提供的运行器环境；不调用任何外部服务。
- **默认只读。** 除非你明确选择交互式菜单中的修复选项（G 或 D），否则工具绝不会修改任何文件——即使如此，也只更新你的根 `README.md`。
- **开源透明。** 完整源码在一个可读的文件中——[`md_connector.py`](md_connector.py)。你可以在运行前审计每一行。
## 🚀 最快上手方式——60秒
**无需包管理器。无需安装。只需复制一个文件。**
### 第一步——将脚本下载到你的项目中
```
# with curl
curl -O https://raw.githubusercontent.com/maneesh-kumar-thakur/MD-Files-Connector/main/md_connector.py
# 或使用 wget
wget https://raw.githubusercontent.com/maneesh-kumar-thakur/MD-Files-Connector/main/md_connector.py
```
或者直接[下载 md_connector.py](https://raw.githubusercontent.com/maneesh-kumar-thakur/MD-Files-Connector/main/md_connector.py)并将其放到你项目中的任何位置。
### 第二步——安装唯一的依赖项
```
pip install rich
```
### 第三步——运行它
```
# 扫描当前目录
python md_connector.py .
# 扫描特定项目
python md_connector.py /path/to/your/project
# 跳过生成 MD_REPORT.md
python md_connector.py . --no-report
```
就这样。你将看到一个仪表盘、一个报告文件，以及一个用于修复任何孤立文件的交互式提示。
## 🤖 集成到 CI — GitHub Action
将以下内容粘贴到你仓库中的 `.github/workflows/md-check.yml` 文件：
```
name: MD Files Connector Check
on:
push:
paths: ["**.md"]
pull_request:
paths: ["**.md"]
jobs:
md-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run MD Files Connector
id: md-connector
uses: maneesh-kumar-thakur/MD-Files-Connector@v1
with:
project-root: "."
exclude-dirs: "node_modules .git venv .venv __pycache__ dist build"
report-path: "MD_REPORT.md"
- name: Show coverage summary
run: |
echo "Coverage : ${{ steps.md-connector.outputs.coverage }}%"
echo "Isolated : ${{ steps.md-connector.outputs.isolated-files }} file(s)"
```
在每次触及 `.md` 文件的推送或 PR 上，该 Action 将：
1. 扫描你的仓库中的所有 Markdown 文件
2. 检查哪些文件已从你的根 `README.md` 链接
3. 将摘要发布到 GitHub Actions 步骤摘要面板
4. 将 `MD_REPORT.md` 作为可下载的构件上传
### Action 输入
| 输入 | 描述 | 默认值 |
|-------|-------------|---------|
| `project-root` | 要扫描的根目录 | `.` |
| `exclude-dirs` | 以空格分隔的要跳过的目录 | `node_modules .git venv ...` |
| `report-path` | MD 报告的输出路径 | `MD_REPORT.md` |
| `skip-report` | 跳过生成报告文件 | `false` |
| `fail-on-isolated` | 如果发现孤立文件则退出码为 1 | `false` |
### Action 输出
| 输出 | 描述 |
|--------|-------------|
| `total-md-files` | 找到的 MD 文件总数（不含根 README） |
| `linked-files` | 根 README 中引用的文件数 |
| `isolated-files` | 未出现在根 README 中的文件数 |
| `coverage` | 链接覆盖率百分比 |
## 📋 示例输出
```
╭───────────────────────────────────────────────────────╮
│ 📋 MD Files Connector │
│ Project root: /my-project │
╰───────────────────────────────────────────────────────╯
📄 Root README README.md
📁 Total MD files (excl. root README) 7
✅ Linked in root README 5
⚠️ Isolated (not in root README) 2
📊 README coverage 71.4%
╭─ ✅ Linked Files ──────────────────────────────────────╮
# File Title Words Sections
────────────────────────────────────────────────────────────────
1 docs/CONTRIBUTING.md Contributing 210 Setup, Guidelines
2 docs/ARCHITECTURE.md Architecture 540 Overview, Components
...
╭─ ⚠️ Isolated Files ───────────────────────────────────╮
# File Title Words First line / description
────────────────────────────────────────────────────────────────────────
1 docs/OLD_API.md Old Api 890 Deprecated. Use v2 API.
2 SCRATCH_NOTES.md Scratch Notes 42 Notes from planning sess
💡 Add these to your root README.md to improve discoverability.
╭─────────────────────────────────────────╮
│ 🔧 Fix isolated files? │
│ 2 file(s) are not linked in README.md │
╰─────────────────────────────────────────╯
[G] Generic Append a new "📎 Other Documentation" section
[D] Docs Looks for any heading matching "docs / documentation"
[M] Manual I'll update the README myself — no changes made
Enter choice (G / D / M):
```
## 🔧 修复选项
当发现孤立文件时，工具会交互式地提示你：
| 选项 | 作用 |
|--------|-------------|
| **G — 通用** | 在你的 README 末尾追加一个 `## 📎 其他文档` 章节，包含所有缺失的链接 |
| **D — 文档** | 找到你的 README 中第一个包含 `doc` 或 `documentation` 单词的标题，并将缺失的链接追加到该处 |
| **M — 手动** | 不做任何操作——由你自行处理 |
## ⚙️ 命令行参考
```
usage: md_connector.py [-h] [--exclude [...]] [--report REPORT] [--no-report] [root]
positional arguments:
root Project root directory (default: current directory)
options:
--exclude [...] Directory names to exclude from scan
--report REPORT Output path for markdown report (default: MD_REPORT.md)
--no-report Skip generating the MD_REPORT.md file
--fail-on-isolated Exit with code 1 if any isolated MD files are found
```
**示例：**
```
# 扫描当前目录并生成报告
python md_connector.py .
# 扫描特定文件夹，不生成报告文件
python md_connector.py /path/to/project --no-report
# 排除额外目录
python md_connector.py . --exclude node_modules .git venv dist tests
# 将报告保存至自定义路径
python md_connector.py . --report docs/coverage-report.md
```
## 📄 生成的报告
在未使用 `--no-report` 的情况下运行时，会在扫描的项目根目录生成 `MD_REPORT.md`，其中包含：
- 摘要统计表（总数、已链接、孤立、覆盖率 %）
- 包含标题、字数和章节的完整已链接文件表
- 包含内容预览的完整孤立文件表
- 可直接粘贴到你根 README 的 Markdown 链接片段
## 贡献
有关开发设置和指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE) © 2026 Maneesh Thakur
标签：GitHub Action, LNA, Markdown文档, Python, README管理, 开源框架, 持续集成, 文件扫描, 文档管理, 文档自动化, 无后门, 终端仪表盘, 自动修复, 覆盖率报告, 软件开发, 逆向工具, 链接检查