index.md

title	Reference
weight	30
summary	Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.

Reference

• CLI commands, flags, exit codes, and output format.
• List workspace links that point at a file.
• Lint Markdown files for style issues.
• List a file's dependency-graph edges (includes, links, catalogs, builds).
• Write a portable, directive-free copy of a Markdown file.
• Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.
• Auto-fix lint issues in Markdown files in place.
• Show built-in documentation for rules, metrics, and concept pages.
• Write .mdsmith.yml from the built-in defaults, a --starter scaffold, or a --from-markdownlint conversion; add curated .mdsmith/ bundles with --add; --force overwrites an existing config and --list prints every starter and pack.
• Inspect declared file kinds and resolve effective rule config per file.
• Selection-style commands that walk the workspace and emit matches.
• Run a Language Server Protocol server on stdio for editor integrations.
• Git merge driver that resolves conflicts inside generated sections.
• Get, list, and rank shared Markdown metrics (file length, token estimate, readability, …).
• Install / manage a pre-merge-commit hook that runs mdsmith fix after a merge.
• Select Markdown files by a CUE expression on front matter.
• Rename a heading or link-reference label and rewrite every dependent edit.
• Review the .mdsmith.yml diff since it was last trusted and update the build trust marker on this clone.
• Print the mdsmith build version and exit.
• Each file under .mdsmith/conventions/ declares one user convention. The basename is the convention name; the file body carries a flavor: plus a rules: map. Sits alongside inline conventions.<name>: in .mdsmith.yml.
• Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.
• The top-level foreign-regions: config lists {start, end} marker pairs whose spanned bytes mdsmith treats as opaque — style rules skip diagnostics inside a matched pair and fixers never rewrite it, while whole-file rules still count the bytes. Glob-scopable via overrides:; a start with no matching end reports MDS073.
• Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.
• Each file under .mdsmith/kinds/ declares one kind. The basename is the kind name; the file body carries the full KindBody — schema, rules, path-pattern:, extends:. Sits alongside inline kinds.<name>: in .mdsmith.yml.
• Every markdownlint rule and the mdsmith rule that covers it, generated from the rule README front matter — the same data mdsmith init --from-markdownlint reads.
• Each file under .mdsmith/schemas/ declares one named schema. The basename is the schema name; the body carries the inline schemas.<name>: keys. A kind references one by name (schema: rfc-v1).
• Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.
• Section-schema reference for inline kinds.<name>.schema: blocks. Covers the heading: discriminator, the regex: matcher (a Go RE2 body with \#(digits) and \#(fmvar(...)) helpers), the repeat: {min, max} cardinality field, and the matching algorithm. proto.md files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.
• mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.
• Settings and troubleshooting for the mdsmith VS Code extension: the five mdsmith.* settings, fix-on-save wiring, and fixes for its known failure modes.
• Each file under .mdsmith/wordlists/ declares one named word-list: an optional extends: parent and an entries: list of literal strings. A rule pulls a list in through its lists: setting and the entries union with the rule's own list. No lists ship compiled in; a project declares every list it uses.