| Installation | Every channel that ships the mdsmith binary, the VS Code extension, or the Claude Code plugin — npm, PyPI, Homebrew, asdf, mise, a Flatpak bundle, the GitHub release, the Visual Studio Marketplace plus Open VSX, and the in-repository Claude Code marketplace — and which channel to pick for which workflow. |
| File Kinds | How to declare file kinds, assign files to them, and read the merged rule config that results. |
| Schemas | Declare a document-structure schema inline on a kind or in a proto.md file, validate headings and front matter, and tighten rule config per section. |
| Use a Markdown convention | Select a built-in convention, declare your own inline, layer rules over its preset, keep the flavor in agreement, and split a convention into its own file. |
| Extract Markdown as data | When a Markdown file’s payload is prose, put it in the body under H2 sections — not in YAML frontmatter. mdsmith extract projects body structure into a JSON tree the same way it projects frontmatter, so the file stays editable as Markdown. |
| Choosing Readability, Conciseness, and Token Budget Metrics | Trade-offs and threshold guidance for readability, structure, length, and token budgets. |
| Coexist with Prettier | Run mdsmith alongside Prettier by ordering mdsmith fix before prettier --write in the same pre-commit hook. |
| Coexist with Vale and remark | Vale owns language-aware brand voice and style; remark owns Markdown AST transformations; mdsmith owns formatting, cross-file integrity, generated sections, and deterministic prose tells such as banned words, required terms, and proper-noun casing. Prose splits by whether a check is mechanical or language-aware. |
| Migrate from markdownlint | Convert a markdownlint config to .mdsmith.yml with mdsmith init --from-markdownlint, review the conversion notes, move inline disables into overrides, and run both linters in parallel until cutover. |
| Progressive Disclosure for AI Agents | Use <?catalog?> with a per-file summary front matter field to emit a one-line index of a directory, so AI coding agents read a few thousand tokens of metadata up front and only Read the files a task actually touches. |
| Open Knowledge Format (OKF) bundles | Author and validate Open Knowledge Format bundles with mdsmith: scaffold the config with mdsmith init --starter okf to require a non-empty type on every concept document, validate bundle-relative cross-links with links.site-root, and generate the index.md listing with <?catalog?>. |
