Check Markdown examples before someone copies them
A project can have a green test suite while its README example is stale. The docs are often the first thing a new user runs, and one missing colon or moved setup link can waste the first few minutes. I built snipverify to check syntax in fenced code blocks and local targets in relative links. It scans Markdown files from a directory or one file at a time. The first release checks JavaScript,…
A project may possess a green test suite despite having outdated README examples. Often, the documentation is the first file a newcomer opens, and a missing colon or misplaced setup link can cause a new user to waste precious minutes. To address this issue, I developed snipverify, a tool that checks the syntax of fenced code blocks and local targets in relative links within Markdown files.
Snipverify scans Markdown files from a directory or an individual file. For every supported code fence—JavaScript, TypeScript, Python, JSON, Bash, and POSIX shell—the tool reports the file and source line when the syntax proves invalid. Importantly, snipverify does not execute the commands or scripts mentioned in the document.
Regarding local links and images, snipverify verifies whether the relative target exists on the user's disk. It skips external URLs and fragment-only links. Unlabeled fences and languages without a designated checker are flagged as skipped, ensuring that unsupported blocks are identifiable without being treated as syntax errors.
The tool offers JSON mode, ideal for continuous integration (CI) pipelines. Developers can incorporate file, line, status, and message data for each finding into their CI workflow. To try snipverify, navigate to the repository root and execute the following command:
npx --yes --package = github:Arthur031221/snipverify snipverify examples/fixed/README.md
The repository includes a deliberately broken Markdown fixture, showcasing a Python syntax error and a relative link pointing to a missing file. This allows users to observe the report before rectifying both issues.
It is essential to note that snipverify is a static check, not an example runner. A passing result does not guarantee that a command will produce the correct output, that its dependencies are installed, or that an external website is reachable. Furthermore, the supported fence labels and Markdown link forms are a limited subset of the formats commonly used in documentation.
Feedback on valid examples rejected by snipverify, desired link forms, and languages that developers would like to see checked is welcome. The source code and issue tracker for snipverify can be found at https://github.com/Arthur031221/snipverify.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
