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
🔧 Auto-fix Markdown formatting.
mdsmith fix rewrites whitespace, headings, code fences,
bare URLs, list indentation, and table alignment in place,
re-running up to 10 passes and stopping early once edits
stabilize. mdsmith check is the read-only CI sibling.
✏️ Live diagnostics wherever you write.
mdsmith lsp emits diagnostics, quick-fixes, and
navigation (definition, references, symbol search, and a
call-hierarchy over <?include?>/<?catalog?> and
cross-file links) — consumed by any LSP-aware editor,
including Neovim, Helix, and JetBrains.
The VS Code extension surfaces all of it with
opt-in fix-on-save (also on Open VSX for
Cursor, VSCodium, Theia, and Gitpod). The
Claude Code plugin
feeds diagnostics and navigation to the agent so it sees
mdsmith inline while editing Markdown.
🔗 Cross-file integrity.
Built-in rules flag broken links and missing anchors
(MDS027),
enforce per-file section schemas
(MDS020),
and keep Markdown in the right folders
(MDS033).
Schemas can be inline on a
file kind or shared via
proto.md files.
🤖 Guardrails for AI-generated docs. Cap file, section, and token-budget size; enforce reading grade and sentence count; flag verbatim copy-paste across files.
📋 Self-maintaining sections.
On mdsmith fix, <?toc?> rebuilds a heading
table-of-contents, <?catalog?> generates an
index — list, table, or any row template — from the front
matter of files matching a glob, and <?include?> splices
in another file. mdsmith merge-driver install registers
a Git driver that auto-resolves merge conflicts inside
those blocks.
📊 Gate releases on doc status.
mdsmith list query 'status: "✅"' plan/ selects files by
a CUE expression on front
matter;
mdsmith metrics rank --by token-estimate --top 10 docs/
ranks files by any shared metric — both ready to pipe into
a release script.
🆚 How does it compare? See:
📦 Installation
CLI:
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
Editor extension (LSP-backed; runs mdsmith lsp):
code --install-extension jeduden.mdsmith # VS Code, Codespaces (Marketplace)
codium --install-extension jeduden.mdsmith # Cursor, VSCodium, Theia, Gitpod (Open VSX)
Any LSP-aware editor (Neovim, Helix, JetBrains via the LSP
plugin) works by pointing at mdsmith lsp.
Claude Code plugin (inline diagnostics plus definition, references, symbol search, and call-hierarchy queries across your docs):
/plugin marketplace add jeduden/mdsmith
/plugin install mdsmith-lsp@mdsmith
/reload-plugins
More: the install guide covers direct downloads and mise (asdf pending). VS Code integration covers settings, code actions, and troubleshooting.
🚀 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. |
list |
Selection-style commands that walk the workspace and emit matches. |
list backlinks |
List workspace links that point at a file. |
list query |
Select Markdown files by a CUE expression on front matter. |
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. |
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. |
|
cue
|
|
|
types
Package types embeds the canonical mdsmith field-type-shortcut library so schema parsing can resolve `created: date` and friends without touching the network.
|
Package types embeds the canonical mdsmith field-type-shortcut library so schema parsing can resolve `created: date` and friends without touching the network. |
|
docs
|
|
|
guides/directives
Package directives embeds the directive guide Markdown files so the LSP hover provider can serve them from the compiled binary without requiring the source tree to be present at runtime.
|
Package directives embeds the directive guide Markdown files so the LSP hover provider can serve them from the compiled binary without requiring the source tree to be present at runtime. |
|
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. |
|
convention
Package convention owns the convention and flavor data shapes independent of any rule.
|
Package convention owns the convention and flavor data shapes independent of any rule. |
|
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. |
|
linkgraph
Package linkgraph extracts Markdown links and heading anchors so the link-validity rule (MDS027) and the `backlinks` subcommand share one implementation of the link walk, anchor slug rules, and target parsing.
|
Package linkgraph extracts Markdown links and heading anchors so the link-validity rule (MDS027) and the `backlinks` subcommand share one implementation of the link walk, anchor slug rules, and target parsing. |
|
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: secret-rotations subcommands.
|
Package release: secret-rotations subcommands. |
|
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. |
|
schema
Package schema models the document-structure schemas that drive MDS020 (required-structure).
|
Package schema models the document-structure schemas that drive MDS020 (required-structure). |
|
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. |