mdsmith-lsp

🔨 mdsmith

[![Build][ci-badge]][ci-link] [![Quality][grc-badge]][grc-link] [![Coverage][cov-badge]][cov-link]

A fast, auto-fixing Markdown linter and formatter for docs, READMEs, and AI-generated content. Checks style, readability, structure, and cross-file integrity. Written in Go.

✨ Why mdsmith

🔧 Stop hand-formatting Markdown. Whitespace, heading style, code fences, bare URLs, list indentation, table alignment — mdsmith fix handles them in place. Multi-pass fixing resolves cascading changes so you don't run it twice. mdsmith check is the read-only sibling for CI.

✏️ See lint errors live in your editor. The [VS Code extension][vsc-mp] runs mdsmith lsp and shows inline squiggles, per-rule quick fixes, and an opt-in source.fixAll.mdsmith action for fix-on-save (set mdsmith.fixOnSave: true to enable). Also on [Open VSX][vsc-ovsx] for Cursor, VSCodium, Theia, and Gitpod. Any LSP-aware editor — Neovim, Helix, JetBrains — works the same way by pointing at mdsmith lsp.

🔗 Catch broken links before they merge. Refactors silently break Markdown links and anchors. cross-file-reference-integrity flags every missing file and missing heading anchor in PR review. Pair it with required-structure to enforce that each file has the sections it should (reusable schemas live in your repo and are referenced by path or named via kinds:), and directory-structure to keep Markdown in the folders it belongs.

🤖 Stop AI from bloating your docs. LLMs produce walls of text. Cap file length with max-file-length, section length with max-section-length, and tokens with token-budget. paragraph-readability and paragraph-structure hold reading-grade and sentence count in line. duplicated-content flags verbatim repetition across files.

📋 Make tables of contents and indexes maintain themselves. Embed <?toc?> for a heading list, <?catalog?> for a table built from front matter, or <?include?> to splice in another file. mdsmith fix regenerates them in place. After a merge conflict in one of these blocks, merge-driver install registers a Git driver that resolves it automatically.

📊 Gate releases on doc status. mdsmith query 'status: "✅"' plan/ lists every plan that's done — pipe it to a release script, or fail the release if anything is still open. mdsmith metrics rank --by token-estimate --top 10 docs/ is the PR-time complement: spot the file an AI just doubled in size before it lands.

📖 Make rule docs readable by AI agents (and humans). mdsmith help rule [name] prints the full rule spec — settings, examples, diagnostics — straight from the binary. No network calls. Drop the output into .cursor/rules, AGENTS.md, or CLAUDE.md and your agent knows the rules without an extra fetch.

🆚 How does it compare? See:

• How mdsmith compares to other Markdown linters.

📦 Installation

go install github.com/jeduden/mdsmith/cmd/mdsmith@latest
npm install -g @mdsmith/cli    # or: npx @mdsmith/cli
pip install mdsmith            # or: uvx mdsmith / pipx install mdsmith

More options live in docs/guides/install.md. It covers direct downloads, the VS Code extension on the Marketplace and Open VSX, and asdf and mise once their registry entries land.

✏️ Editor integration

The mdsmith VS Code extension renders diagnostics inline. Each fixable rule contributes a quick fix. A source.fixAll.mdsmith action runs mdsmith fix on the buffer.

# stock VS Code, GitHub Codespaces, GitHub.dev (Marketplace)
code --install-extension jeduden.mdsmith
# Cursor, VSCodium, Theia, Gitpod (Open VSX)
codium --install-extension jeduden.mdsmith

The extension is a thin LSP client. The lint pipeline runs in the Go binary, so any LSP-aware editor (Neovim, Helix, JetBrains via the LSP plugin) gets the same diagnostics by pointing at mdsmith lsp.

See VS Code Integration for settings (mdsmith.path, mdsmith.run, mdsmith.fixOnSave, mdsmith.trace.server), code actions, and troubleshooting.

🚀 Usage

mdsmith <command> [flags] [files...]

Commands