README
¶
🔨 mdsmith
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.
🔗 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:
📦 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.
🚀 Usage
mdsmith <command> [flags] [files...]
Commands
| Command | Description |
|---|---|
check |
Lint Markdown files for style issues. |
fix |
Auto-fix lint issues in Markdown files in place. |
help |
Show built-in documentation for rules, metrics, and concept pages. |
init |
Generate a default .mdsmith.yml config in the current directory. |
kinds |
Inspect declared file kinds and resolve effective rule config per file. |
lsp |
Run a Language Server Protocol server on stdio for editor integrations. |
merge-driver |
Git merge driver that resolves conflicts inside generated sections. |
metrics |
List and rank shared Markdown metrics (file length, token estimate, readability, …). |
pre-merge-commit |
Install / manage a pre-merge-commit hook that runs mdsmith fix after a merge. |
query |
Select Markdown files by a CUE expression on front matter. |
version |
Print the mdsmith build version and exit. |
Files can be paths, directories (walked recursively for *.md
and *.markdown), or glob patterns. Directories respect
.gitignore by default;
use --no-gitignore to override. Explicitly named files are
never filtered by .gitignore.
Examples
mdsmith check docs/ # lint a directory
mdsmith fix README.md # auto-fix in place
mdsmith check -f json docs/ # JSON output
mdsmith metrics rank --by bytes --top 10 .
See the CLI reference for shared flags, exit codes, output format, and configuration merge semantics. Individual subcommand pages above cover their own flags and examples.
⚙️ Configuration
Run mdsmith init to generate a .mdsmith.yml with every rule and its
defaults. Without a config, rules run with built-in defaults.
rules:
line-length:
max: 120
fenced-code-language: false
ignore:
- "vendor/**"
overrides:
- glob: ["CHANGELOG.md"]
rules:
no-duplicate-headings: false
Rules are true (defaults), false (off), or an object with settings.
overrides apply per file pattern; later entries take precedence.
Config is discovered by walking up to the repo root; --config overrides.
Commit .mdsmith.yml so contributors share the same rule settings and
mdsmith upgrades become an explicit, reviewable change. Run
mdsmith version to see the build you have installed.
📚 More
- Guides — directives, structure, migration
- Rule directory — every rule with status
- CLI reference
- Contributor guide — Go 1.24+, build, test, style
📄 License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
corpusctl
command
|
|
|
mdsmith
command
|
|
|
mdsmith-release
command
mdsmith-release is the internal CLI the GitHub Actions release pipeline invokes.
|
mdsmith-release is the internal CLI the GitHub Actions release pipeline invokes. |
|
internal
|
|
|
archetype/gensection
Package gensection provides a reusable engine for marker-based generated-section rules.
|
Package gensection provides a reusable engine for marker-based generated-section rules. |
|
concepts
Package concepts provides embedded concept-page documentation for mdsmith topics that span multiple rules or subsystems.
|
Package concepts provides embedded concept-page documentation for mdsmith topics that span multiple rules or subsystems. |
|
discovery
Package discovery finds Markdown files by expanding glob patterns from config.
|
Package discovery finds Markdown files by expanding glob patterns from config. |
|
explain
Package explain attaches per-leaf rule provenance to lint diagnostics.
|
Package explain attaches per-leaf rule provenance to lint diagnostics. |
|
fieldinterp
Package fieldinterp provides {field} placeholder interpolation with CUE path resolution for nested front-matter access.
|
Package fieldinterp provides {field} placeholder interpolation with CUE path resolution for nested front-matter access. |
|
githooks
Package githooks provides utilities shared between the mdsmith CLI and the git-hook-sync rule for managing the pre-merge-commit hook, merge-driver assignments in .gitattributes, and discovery of files that contain generated-section directives.
|
Package githooks provides utilities shared between the mdsmith CLI and the git-hook-sync rule for managing the pre-merge-commit hook, merge-driver assignments in .gitattributes, and discovery of files that contain generated-section directives. |
|
globpath
Package globpath provides glob matching and pattern utilities for mdsmith config surfaces: ignore:, overrides:, kind-assignment:, and rule settings (allowed:, include:, exclude:, budgets[].glob).
|
Package globpath provides glob matching and pattern utilities for mdsmith config surfaces: ignore:, overrides:, kind-assignment:, and rule settings (allowed:, include:, exclude:, budgets[].glob). |
|
kindsout
Package kindsout renders the output of the 'mdsmith kinds' subcommand surface: declared-kind bodies, per-file resolutions, and per-rule merge chains.
|
Package kindsout renders the output of the 'mdsmith kinds' subcommand surface: declared-kind bodies, per-file resolutions, and per-rule merge chains. |
|
lsp
Package lsp implements a minimal Language Server Protocol surface for mdsmith.
|
Package lsp implements a minimal Language Server Protocol surface for mdsmith. |
|
lsp/index
Package index builds and maintains the symbol graph that powers mdsmith's LSP navigation methods (documentSymbol, definition, references, workspace/symbol, callHierarchy).
|
Package index builds and maintains the symbol graph that powers mdsmith's LSP navigation methods (documentSymbol, definition, references, workspace/symbol, callHierarchy). |
|
placeholders
Package placeholders provides a shared vocabulary of placeholder tokens that rules can opt into to treat template content as opaque rather than content violations.
|
Package placeholders provides a shared vocabulary of placeholder tokens that rules can opt into to treat template content as opaque rather than content violations. |
|
release
Package release provides the helper logic the release workflow invokes via cmd/mdsmith-release/.
|
Package release provides the helper logic the release workflow invokes via cmd/mdsmith-release/. |
|
rules/all
Package all is a blank-import barrel that registers every production rule with the rule registry.
|
Package all is a blank-import barrel that registers every production rule with the rule registry. |
|
rules/ambiguousemphasis
Package ambiguousemphasis implements MDS047, which flags emphasis runs whose meaning a human cannot predict at a glance.
|
Package ambiguousemphasis implements MDS047, which flags emphasis runs whose meaning a human cannot predict at a glance. |
|
rules/build
Package build implements MDS039, which validates <?build?> directive parameters and keeps the body in sync with the recipe's body-template.
|
Package build implements MDS039, which validates <?build?> directive parameters and keeps the body in sync with the recipe's body-template. |
|
rules/duplicatedcontent
Package duplicatedcontent implements MDS037, which flags substantial paragraphs that also appear verbatim in another Markdown file in the project root after whitespace and case normalization.
|
Package duplicatedcontent implements MDS037, which flags substantial paragraphs that also appear verbatim in another Markdown file in the project root after whitespace and case normalization. |
|
rules/githooksync
Package githooksync implements MDS048, the git-hook-sync rule.
|
Package githooksync implements MDS048, the git-hook-sync rule. |
|
rules/listmarkerstyle
Package listmarkerstyle implements MDS045, which pins the bullet character for unordered lists.
|
Package listmarkerstyle implements MDS045, which pins the bullet character for unordered lists. |
|
rules/markdownflavor
Package markdownflavor implements MDS034, which validates Markdown against a declared target flavor (commonmark, gfm, goldmark, pandoc, phpextra, multimarkdown, myst, or any) and flags syntax the target renderer will not understand.
|
Package markdownflavor implements MDS034, which validates Markdown against a declared target flavor (commonmark, gfm, goldmark, pandoc, phpextra, multimarkdown, myst, or any) and flags syntax the target renderer will not understand. |
|
rules/markdownflavor/ext
Package ext implements detection-only goldmark extensions used by MDS034 (markdown-flavor) to flag syntax that varies across Markdown flavors.
|
Package ext implements detection-only goldmark extensions used by MDS034 (markdown-flavor) to flag syntax that varies across Markdown flavors. |
|
rules/noreferencestyle
Package noreferencestyle implements MDS043, which forbids reference-style links and footnotes.
|
Package noreferencestyle implements MDS043, which forbids reference-style links and footnotes. |
|
rules/nospaceincodespans
Package nospaceincodespans implements MDS052, which flags inline code spans with leading or trailing whitespace inside the backticks.
|
Package nospaceincodespans implements MDS052, which flags inline code spans with leading or trailing whitespace inside the backticks. |
|
rules/noundefinedreferencelabels
Package noundefinedreferencelabels implements MDS054, which flags reference-style links and images whose label has no matching link reference definition in the file.
|
Package noundefinedreferencelabels implements MDS054, which flags reference-style links and images whose label has no matching link reference definition in the file. |
|
rules/nounusedlinkdefinitions
Package nounusedlinkdefinitions implements MDS053, which flags link reference definitions that are never used by any reference-style link or image, and definitions that duplicate an existing label.
|
Package nounusedlinkdefinitions implements MDS053, which flags link reference definitions that are never used by any reference-style link or image, and definitions that duplicate an existing label. |
|
rules/orderedlistnumbering
Package orderedlistnumbering implements MDS046, which pins how ordered list items are numbered in the source: literal sequential (1.
|
Package orderedlistnumbering implements MDS046, which pins how ordered list items are numbered in the source: literal sequential (1. |
|
rules/propernames
Package propernames implements MDS050, which checks that proper names (e.g.
|
Package propernames implements MDS050, which checks that proper names (e.g. |
|
rules/recipesafety
Package recipesafety implements MDS040, which validates every command in build.recipes for shell-safety at lint time.
|
Package recipesafety implements MDS040, which validates every command in build.recipes for shell-safety at lint time. |
|
rules/settings
Package settings provides shared helpers for coercing rule-configuration values decoded from YAML/CUE into Go types.
|
Package settings provides shared helpers for coercing rule-configuration values decoded from YAML/CUE into Go types. |
|
rules/toc
Package toc implements MDS038, the <?toc?> generated-section directive that emits a nested heading list linked to GitHub-style anchors.
|
Package toc implements MDS038, the <?toc?> generated-section directive that emits a nested heading list linked to GitHub-style anchors. |
|
rules/tocdirective
Package tocdirective implements MDS035, which flags renderer-specific table-of-contents directives that render as literal text on CommonMark and goldmark.
|
Package tocdirective implements MDS035, which flags renderer-specific table-of-contents directives that render as literal text on CommonMark and goldmark. |
|
testutil
Package testutil holds small helpers shared across test binaries.
|
Package testutil holds small helpers shared across test binaries. |
|
yamlutil
Package yamlutil provides safe YAML parsing and marshaling helpers.
|
Package yamlutil provides safe YAML parsing and marshaling helpers. |