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 under mdsmith archetypes), 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
🚀 Usage
mdsmith <command> [flags] [files...]
Commands
| Command | Description |
|---|---|
check |
Lint files (default command) |
fix |
Auto-fix issues in place |
query |
Select files by CUE expression on front matter |
help |
Show help for rules and topics |
metrics |
List and rank Markdown metrics |
merge-driver |
Git merge driver for regenerable sections |
archetypes |
Discover, show, and locate archetype schemas |
init |
Generate .mdsmith.yml |
version |
Print version, 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.
Flags
| Flag | Description |
|---|---|
-c, --config |
Config path |
-f, --format |
text or json |
--no-color |
Plain output |
--no-gitignore |
Skip gitignore |
-q, --quiet |
Quiet mode |
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 .
Output
Diagnostics are printed to stderr with source context when available:
README.md:10:81 MDS001 line too long (135 > 80)
8 | Context lines appear above and below the diagnostic with line numbers.
9 | They help you see the surrounding code at a glance.
10 | This line is deliberately made long so it exceeds the eighty character limit and keeps going and going.
·····················································································^
11 | A dot path runs from column 1 to the caret, marking the line and column.
12 | Up to two lines of context are shown on each side.
Exit codes
| Code | Meaning |
|---|---|
| 0 | No lint issues found |
| 1 | Lint issues found |
| 2 | Runtime or configuration error |
⚙️ 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:
- files: ["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
|
|
|
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. |
|
archetypes
Package archetypes discovers user-supplied required-structure archetype schemas from a set of configured root directories.
|
Package archetypes discovers user-supplied required-structure archetype schemas from a set of configured root directories. |
|
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. |
|
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. |
|
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. |
|
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/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/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/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. |