Configuration

Don't Panic. The contract says what the guide must contain; the config decides which alarms actually wake the crew.

mdv init config              # writes a commented-out mediva.config.mjs, never overwrites
mdv check --config ci.mjs    # an explicit config
mdv check --no-config        # built-in rules only

An unknown key exits 2.

What blocks: rules and overridesCopy Anchor Link

export default {
  rules: {
    "too-few-words": "off",   // turn it off everywhere
    "missing-block": "warn",  // report it, never fail on it
  },
  overrides: [
    { files: ["docs/adr/**"], rules: { "missing-section": "off" } },
  ],
};

mdv explain <path> lists the settings that apply to a document and every finding config changed.

A document never relaxes its own contract: an <!-- mdv: … --> comment in it is not a directive. For a one-off exception, scope an overrides entry to its path.

Lint findings (markdownlint, unclosed-fence, unclosed-comment, fenced-output, frontmatter-unreadable) are always errors: no rules entry turns them off or down, and naming one in rules is a config error.

Lint gate: markdownlint rulesCopy Anchor Link

The lint gate runs first on every document: markdownlint's rules, then mediva's own checks (an unclosed fence, an unclosed <!-- comment, a document fenced whole, front matter that does not read). lint is markdownlint's own configuration object, and the only place lint rules are chosen; no contract, document, flag or plugin selects them.

export default {
  lint: { default: false, MD005: true, MD056: true, MD046: { style: "fenced" }, MD040: true }, // the default set, plus fence languages
};

lint replaces the default set (MD005 list indent, MD056 table column count, MD046 indented code; mdv explain markdownlint prints it), so list those too if you want to keep them. MD018 (##Heading without a space) is off by default because it also matches prose that opens with #1234; switch it on here if your documents never do. Each rule is true, false or its options: a lint finding is always an error, so a severity ("warning", "error", { severity }) is a config error. mediva's own checks always run and cannot be named here.

PluginsCopy Anchor Link

Config is found up to the git root and is executable code; --no-config skips it. Write one with Authoring plugins, validate with mdv debug plugin <path>.