| 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 brand voice and prose style; remark owns Markdown AST transformations; mdsmith owns formatting, cross-file integrity, and generated sections. They sit side by side in CI without overlap. |
| 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. |
