#[must_use]
pub fn render_reference_markdown() -> String {
let mut out = String::with_capacity(8192);
out.push_str(REFERENCE_PREAMBLE);
out.push_str("<!-- BEGIN GENERATED: do not edit. Regenerate by running `cargo xtask doc-config`. -->\n\n");
render_reference_section(&mut out, "[lint]", "lint.");
render_reference_section(&mut out, "[fmt]", "fmt.");
render_reference_section(&mut out, "[parse]", "parse.");
render_reference_section(&mut out, "[render]", "render.");
out.push_str("<!-- END GENERATED -->\n");
out
}
#[must_use]
pub fn render_default_toml() -> String {
let mut out = String::with_capacity(12_288);
out.push_str("# mdwright configuration\n");
out.push_str("#\n");
out.push_str("# Generated by `mdwright config init`. Every key below is set to\n");
out.push_str("# mdwright's current default. Edit or delete values to fit this project.\n");
let mut current_table = "";
for field in SCHEMA_FIELDS {
let Some((table, key)) = field.key.rsplit_once('.') else {
continue;
};
if table == current_table {
out.push('\n');
} else {
current_table = table;
out.push('\n');
out.push('[');
out.push_str(table);
out.push_str("]\n");
}
out.push_str("# Type: ");
out.push_str(field.ty);
out.push_str(".\n");
for line in field.description.lines() {
out.push_str("# ");
out.push_str(line);
out.push('\n');
}
out.push_str(key);
out.push_str(" = ");
out.push_str(field.default);
out.push('\n');
}
out
}
struct FieldDoc {
key: &'static str,
ty: &'static str,
default: &'static str,
description: &'static str,
cli_override: Option<&'static str>,
}
const SCHEMA_FIELDS: &[FieldDoc] = &[
FieldDoc {
key: "lint.preset",
ty: "\"default\" | \"all\" | \"none\"",
default: "\"default\"",
description: "Baseline lint rule set. Use `default` for curated defaults, `all` for every registered rule, or `none` with `lint.select` for an explicit set.",
cli_override: Some("--rules"),
},
FieldDoc {
key: "lint.select",
ty: "array of string",
default: "[]",
description: "Exact lint rule names to enable when `lint.preset = \"none\"`. Preset names are not valid rule names here.",
cli_override: Some("--rules"),
},
FieldDoc {
key: "lint.extend-select",
ty: "array of string",
default: "[]",
description: "Lint rule names to add on top of `lint.preset`.",
cli_override: Some("--rules"),
},
FieldDoc {
key: "lint.ignore",
ty: "array of string",
default: "[]",
description: "Lint rule names to remove after applying `lint.preset`, `lint.select`, and `lint.extend-select`.",
cli_override: Some("--rules"),
},
FieldDoc {
key: "lint.exclude",
ty: "array of string",
default: "[]",
description: "Gitignore-style patterns. Matching files are dropped from lint runs. Patterns are anchored to the directory containing the config file.",
cli_override: None,
},
FieldDoc {
key: "lint.info-strings.extra",
ty: "array of string",
default: "[]",
description: "Project-specific additions to the `info-string-typo` allowlist. The stdlib default allowlist still applies.",
cli_override: None,
},
FieldDoc {
key: "fmt.profile",
ty: "\"preserve\" | \"mdformat\"",
default: "\"preserve\"",
description: "Formatter style profile. `preserve` keeps mdwright's identity-oriented defaults; `mdformat` applies mdformat-compatible defaults where verified rewrites can preserve semantics. Explicit `[fmt]` keys override profile defaults.",
cli_override: None,
},
FieldDoc {
key: "fmt.wrap",
ty: "\"keep\" | \"no\" | int",
default: "\"keep\"",
description: "Wrap mode for prose paragraphs. `keep` leaves existing breaks alone; `no` forbids new breaks; an integer enforces that display-column budget for breakable lines in every formatter profile.",
cli_override: None,
},
FieldDoc {
key: "fmt.wrap-strategy",
ty: "\"stable\" | \"balanced\"",
default: "\"stable\"",
description: "Reflow strategy used when `fmt.wrap` is an integer. `stable` greedily fills soft-break runs and is the default; `balanced` rebalances paragraphs for more even line lengths.",
cli_override: None,
},
FieldDoc {
key: "fmt.italic",
ty: "\"asterisk\" | \"underscore\" | \"preserve\"",
default: "\"preserve\"",
description: "Italic delimiter canonicalisation. `preserve` leaves source bytes; `asterisk` or `underscore` opts into the post-pass rewrite. See [Style knobs](format/style.md).",
cli_override: None,
},
FieldDoc {
key: "fmt.strong",
ty: "\"asterisk\" | \"underscore\" | \"preserve\"",
default: "\"preserve\"",
description: "Strong-emphasis delimiter canonicalisation. Independent of `fmt.italic`: `*italic*` with `__strong__` is expressible.",
cli_override: None,
},
FieldDoc {
key: "fmt.list-marker",
ty: "\"dash\" | \"asterisk\" | \"plus\" | \"preserve\"",
default: "\"preserve\"",
description: "Unordered-list bullet canonicalisation. Each marker is rewritten through a marker-local fact and the family commits only after verification.",
cli_override: None,
},
FieldDoc {
key: "fmt.ordered-list",
ty: "\"one\" | \"consistent\" | \"preserve\"",
default: "\"preserve\"",
description: "Ordered-list number canonicalisation. `one` rewrites markers to `1.` only when verification preserves the list start; `consistent` renumbers each list from the source's first item; `preserve` keeps source numbering verbatim.",
cli_override: None,
},
FieldDoc {
key: "fmt.thematic-break",
ty: "\"dash\" | \"asterisk\" | \"underscore\" | \"underscore-70\" | \"preserve\"",
default: "\"preserve\"",
description: "Thematic-break canonicalisation. Fixed character modes preserve the source repeat count and spacing; `underscore-70` rewrites the whole break line to mdformat's 70 underscores.",
cli_override: None,
},
FieldDoc {
key: "fmt.trailing-newline",
ty: "\"preserve\" | \"strip\" | \"ensure\" | bool",
default: "\"preserve\"",
description: "Trailing-newline policy at the document boundary. `true` is accepted as a synonym for `ensure` and `false` for `strip`.",
cli_override: None,
},
FieldDoc {
key: "fmt.end-of-line",
ty: "\"lf\" | \"crlf\" | \"keep\"",
default: "\"lf\"",
description: "Line-ending normalisation. `keep` adopts the first newline seen in the source.",
cli_override: None,
},
FieldDoc {
key: "fmt.exclude",
ty: "array of string",
default: "[]",
description: "Formatter-specific exclude globs, independent of `[lint] exclude`.",
cli_override: None,
},
FieldDoc {
key: "fmt.heading-attrs",
ty: "\"preserve\" | \"canonicalise\"",
default: "\"preserve\"",
description: "ATX heading `{#id .class key=val}` trailer emission. `preserve` emits the source trailer byte-verbatim. `canonicalise` emits id first, then classes, then key-value pairs.",
cli_override: None,
},
FieldDoc {
key: "fmt.refs.placement",
ty: "\"end\" | \"preserve\"",
default: "\"end\"",
description: "Where reference-link definitions are emitted: gathered and sorted at the end of the document, or kept in source order.",
cli_override: None,
},
FieldDoc {
key: "fmt.refs.style",
ty: "\"bare\" | \"angle\" | \"preserve\"",
default: "\"preserve\"",
description: "Destination style for reference-link and inline-link URLs. `preserve` keeps each destination's source form; `bare` strips wrapping `<...>` where the bare form still parses; `angle` wraps every destination in `<...>`.",
cli_override: None,
},
FieldDoc {
key: "fmt.footnotes.placement",
ty: "\"end\" | \"preserve\"",
default: "\"preserve\"",
description: "Where footnote definitions are emitted. Default is `preserve` because pulldown-cmark's HTML renderer ties footnote position to parse order; moving definitions would change the rendered HTML.",
cli_override: None,
},
FieldDoc {
key: "fmt.tables.style",
ty: "\"compact\" | \"align\" | \"preserve\"",
default: "\"compact\"",
description: "GFM table spacing policy. `compact` trims cell padding to one space on each side; `align` pads columns by display width; `preserve` keeps source cell spacing.",
cli_override: None,
},
FieldDoc {
key: "fmt.lists.continuation-indent",
ty: "\"marker-width\" | \"four-space\"",
default: "\"marker-width\"",
description: "Continuation indentation for wrapped list-item paragraphs. `marker-width` aligns to the source marker width; `four-space` matches mdformat's list continuation spelling.",
cli_override: None,
},
FieldDoc {
key: "fmt.frontmatter.preserve",
ty: "bool",
default: "true",
description: "Whether to emit document frontmatter byte-verbatim. `false` strips it.",
cli_override: None,
},
FieldDoc {
key: "fmt.math.normalise",
ty: "bool",
default: "false",
description: "Whether whole-block math regions are normalised. Off by default because math bytes are opaque to CommonMark.",
cli_override: None,
},
FieldDoc {
key: "fmt.math.render",
ty: "\"none\" | \"commonmark-katex\" | \"dollar\"",
default: "\"none\"",
description: "Math delimiter rendering policy for downstream renderers. `none` preserves source math regions; `commonmark-katex` records intent without rewriting; `dollar` rewrites bracket and paren math to dollar delimiters.",
cli_override: None,
},
FieldDoc {
key: "parse.math.delimiters",
ty: "\"tex\" | \"github\"",
default: "\"tex\"",
description: "Math delimiter recognition policy. `tex` recognises `\\(...\\)`, `\\[...\\]`, and LaTeX environments; `github` also recognises `$...$` and `$$...$$`.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.definition-lists",
ty: "bool",
default: "true",
description: "Recognise `Term\\n: definition\\n` definition lists. Turn off on non-mkdocs corpora to suppress recognition.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.abbreviation-lists",
ty: "bool",
default: "true",
description: "Recognise `*[ABBR]: definition` abbreviation declarations as a scan-and-preserve overlay. mdwright does not expand occurrences; the downstream renderer does.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.heading-attribute-lists",
ty: "bool",
default: "true",
description: "Recognise `# Heading {#id .class}` trailers via pulldown's heading-attribute extension. When off, the trailer reads as plain text in the heading body.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.block-attribute-lists",
ty: "bool",
default: "true",
description: "Recognise `{ .class }` on a line by itself after a non-empty block as a scan-and-preserve overlay. Inline attribute lists are out of scope.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.gfm.autolinks",
ty: "\"disabled\" | \"urls\" | \"urls-and-emails\"",
default: "\"urls-and-emails\"",
description: "Recognise GFM bare URL and email autolinks as document facts and render them as links. Use `urls` to leave bare emails as text or `disabled` for strict CommonMark-style text treatment.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.gfm.tagfilter",
ty: "bool",
default: "true",
description: "Apply GFM tagfiltering when rendering or building semantic signatures. This escapes the raw HTML tags that cmark-gfm filters, without rewriting source bytes.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.myst.directive-containers",
ty: "bool",
default: "true",
description: "Recognise MyST `:::{name}` directive containers with `:KEY: value` options as a scan-and-preserve overlay. mdwright does not expand directives; downstream renderers do.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.myst.inline-roles",
ty: "bool",
default: "true",
description: "Recognise MyST `` {role}`payload` `` inline roles as a scan-and-preserve overlay inside paragraph text.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.myst.substitution-references",
ty: "bool",
default: "true",
description: "Recognise MyST `{{name}}` inline substitution references as a scan-and-preserve overlay. Declarations live in YAML frontmatter and round-trip through the frontmatter path.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.myst.comments",
ty: "bool",
default: "true",
description: "Recognise MyST `%` line comments at line-start as a scan-and-preserve overlay.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.pandoc.fenced-divs",
ty: "bool",
default: "true",
description: "Recognise Pandoc `::: {.cls}` fenced div openers. The closer is a colon-only line of matching count.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.pandoc.short-form-divs",
ty: "bool",
default: "true",
description: "Recognise Pandoc `:::name` fenced div openers.",
cli_override: None,
},
FieldDoc {
key: "parse.extensions.pandoc.inline-attribute-spans",
ty: "bool",
default: "true",
description: "Recognise Pandoc `[content]{.cls}` inline attribute spans as a scan-and-preserve overlay.",
cli_override: None,
},
FieldDoc {
key: "render.profile",
ty: "\"pulldown\" | \"cmark-gfm\"",
default: "\"pulldown\"",
description: "HTML spelling profile for `mdwright render`. `pulldown` preserves the default renderer; `cmark-gfm` matches cmark-gfm spelling where parser semantics already agree.",
cli_override: Some("--render-profile"),
},
];
const REFERENCE_PREAMBLE: &str = r#"# Configuration
mdwright reads configuration from (in precedence order):
1. The file given via `--config PATH`.
2. The nearest ancestor config discovered by walking upward from the
current directory. At each ancestor, candidates are tried in this
order: `.mdwright.toml`, `mdwright.toml`,
`pyproject.toml` containing a `[tool.mdwright]` table. The walk
stops at the filesystem root or at the first directory containing
`.git/` (the workspace boundary).
3. Built-in defaults.
A `pyproject.toml` *without* `[tool.mdwright]` does not stop the walk;
discovery continues to the parent directory. A `.mdwright.toml` wins
over a `pyproject.toml` in the same directory (matching ruff's
"more-specific-name first" rule).
Run `mdwright config init` to create a documented `.mdwright.toml`
starter file with every option set to its default.
## Single-file integration via `pyproject.toml`
For projects that already use `pyproject.toml`, the entire mdwright
configuration can live there under `[tool.mdwright]`:
```toml
# pyproject.toml
[tool.mdwright]
lint.preset = "default"
lint.extend-select = ["latex-command"]
[tool.mdwright.fmt]
wrap = 100
```
## CLI overrides
The following knobs accept CLI flags that take precedence over the
config file:
- `lint.preset`, `lint.select`, `lint.extend-select`, `lint.ignore`: `--rules`
- `render.profile`: `mdwright render --render-profile`
- `--no-suppress` toggles whether `<!-- mdwright: allow ... -->`
comments are honoured; there is no config-file equivalent.
All `[fmt]` knobs are config-file-only.
## Schema reference
"#;
fn render_reference_section(out: &mut String, heading: &str, prefix: &str) {
out.push_str("### `");
out.push_str(heading);
out.push_str("` and nested tables\n\n");
out.push_str("| Key | Type | Default | CLI override | Description |\n");
out.push_str("| --- | --- | --- | --- | --- |\n");
for field in SCHEMA_FIELDS {
if !field.key.starts_with(prefix) {
continue;
}
let cli = field.cli_override.unwrap_or("none");
let ty_escaped = field.ty.replace('|', "\\|");
out.push_str("| `");
out.push_str(field.key);
out.push_str("` | ");
out.push_str(&ty_escaped);
out.push_str(" | `");
out.push_str(field.default);
out.push_str("` | `");
out.push_str(cli);
out.push_str("` | ");
out.push_str(field.description);
out.push_str(" |\n");
}
out.push('\n');
}