DEV Community

Maneesh Thakur
Maneesh Thakur

Posted on

MD Files Connector — Stop Losing Track of Your Markdown Docs

#github #devops #python #documentation

The Problem

Your project has a CONTRIBUTING.md, an ARCHITECTURE.md, a docs/API.md. You wrote them. Then you forgot about them.

Nobody links to them. Nobody reads them. They just exist — invisible.

The Fix

MD Files Connector is a CLI tool + GitHub Action that scans your project for every .md file and checks which ones are actually linked from your root README.md.

Files that aren't linked? Isolated. Nobody will find them.

bash
python md_connector.py .
Enter fullscreen mode Exit fullscreen mode

That's it. You get a rich terminal dashboard:

📁 Total MD files     7
✅ Linked in README   5
⚠️  Isolated           2
📊 Coverage          71.4%
Enter fullscreen mode Exit fullscreen mode

And an interactive fix menu to auto-link the isolated ones into your README — no manual editing needed.

Run it in CI

Drop this into .github/workflows/md-check.yml:

`yaml
name: Run MD Files Connector
uses: Maneesh-Relanto/MD-Files-Connector@v1.0.0
with:
fail-on-isolated: "true"
Enter fullscreen mode Exit fullscreen mode

Now every PR that ships an unlinked .md file fails the check. Docs stay honest automatically.

Key facts

  • Zero config — one Python file, one command
  • Language agnostic — works with any repo regardless of tech stack
  • Privacy first — nothing leaves your machine, no network calls
  • CI-friendly — --fail-on-isolated exits with code 1
  • Auto-fix — interactive menu patches your README for you
  • Open source — MIT, single readable file you can audit

Links

Please share the feedback and happy to hear on the suggestions.

Top comments (0)