`options`: Typed configuration schema for the MyST plugin#

MystOptions is the single source of truth for every [plugin.myst] knob: the argparse CLI group, the read-with-defaults over mdformat’s option dict, per-key validation (typo-catching), and a published JSON Schema are all generated from its fields. mdformat itself provides no schema, defaults, or validation for plugin options – it only checks “is this a dict” – so this is the config foundation the rest of the plugin’s options build on, added one field at a time.

Read the effective options at render/postprocess time with MystOptions.from_context; register the CLI flags with MystOptions.add_arguments from plugin.add_cli_argument_group. Field defaults reproduce today’s behavior, so an empty [plugin.myst] is a no-op.

fold_aware_tables is enabled by default: Markdown table columns measure each cell’s serialized inline markup, ignoring only typically-hidden material such as link destinations and targets.

setext_headings is enabled by default: ordinary Setext headings normalize to ATX, while a list label followed by a unary nested dash remains an empty nested list.

Typed configuration schema for the MyST plugin.

fold_aware_tables is enabled by default: Markdown table columns measure each cell’s serialized inline markup, ignoring only typically-hidden material such as link destinations and targets.

setext_headings is enabled by default: ordinary Setext headings normalize to ATX, while a list label followed by a unary nested dash remains an empty nested list.

class myform.options.MystOptions(*, sembr: bool = False, ignore_comment: str = 'myform-ignore', ignore_start_comment: str = 'myform-ignore-start', ignore_end_comment: str = 'myform-ignore-end', ignore_file_comment: str = 'myform-ignore-file', role_trim: bool = True, directive_options_style: 'auto' | 'prefix' | 'yaml' = 'auto', directive_options_yaml_threshold: Annotated[int, Ge(ge=0)] = 3, target_hug_headings: bool = True, target_hug_blocks: bool = True, tight_heading_level: Annotated[int, Ge(ge=1)] = 5, directive_fence_style: 'preserve' | 'colon' | 'backtick' = 'preserve', fold_aware_tables: bool = True, setext_headings: bool = True)#

The typed [plugin.myst] configuration surface.

Every field is one config key: its type drives CLI-flag generation and validation, its default reproduces the plugin’s current behavior, and its description feeds both --help and the published JSON Schema. Instances are frozen and reject unknown keys, so a misspelled option in .mdformat.toml is a loud validation error rather than a silent no-op.

sembr: bool#: Reflow paragraphs to one sentence per line (semantic line breaks). See Sembr.

ignore_comment: str#: HTML-comment marker that skips formatting of the next block. See Ignore.

ignore_start_comment: str#: HTML-comment marker that opens a preserved range (closed by ignore_end_comment).

ignore_end_comment: str#: HTML-comment marker that closes a range opened by ignore_start_comment.

ignore_file_comment: str#: HTML-comment marker that preserves the whole file verbatim.

role_trim: bool#: Strip whitespace around the content of an inline MyST role. See Renderer.

directive_options_style: 'auto' | 'prefix' | 'yaml'#

auto (prefix, or YAML past the threshold), always prefix (:key: val), or always yaml (a --- block). See Renderer.

Type:: How to render directive options

directive_options_yaml_threshold: int#: In auto style, render options as a YAML block once they exceed this many lines.

target_hug_headings: bool#: Hug a target to the heading that follows it (no blank line between). See Spacer.

target_hug_blocks: bool#: Hug a target to a following non-heading block (no blank line between). See Spacer.

tight_heading_level: int#: Headings at this level or deeper render “tight” (hug the next block). Above 6 disables it.

directive_fence_style: 'preserve' | 'colon' | 'backtick'#: Force directive fences to one character, or preserve the source’s. See Renderer.

fold_aware_tables: bool#: Size Markdown table columns from visible cell content, ignoring typically-hidden syntax.

setext_headings: bool#: Recognize Setext headings except where a nested empty list item is equally valid Markdown.

classmethod from_context(ctx: Any) → Self#

Build validated options from an mdformat RenderContext.

Reads the [plugin.myst] sub-mapping out of ctx.options (where both TOML config and CLI flags land) and validates it into a typed instance. Prefer cached on hot per-node paths so the model is validated once per render rather than once per node.

classmethod cached(ctx: Any) → Self#

Return the render run’s options, validating once and memoizing on ctx.env.

Postprocessors run per node across the whole tree; ctx.env is one object shared for the render, so caching there keeps validation O(1) per format instead of O(nodes).

classmethod from_options(plugin_myst: Mapping[str, Any]) → Self#

Build validated options from a raw [plugin.myst] mapping.

None values – an unset CLI flag carries default=None – are dropped so the field default applies instead of a null overriding it. An unknown key is warned about and ignored rather than raising: typos stay visible, but a stray key (e.g. version skew across plugin releases) must not abort a whole format run over many files. A wrong value type still raises, since that is a genuine misconfiguration of a real option.

classmethod add_arguments(group: _ArgumentGroup) → None#

The argparse default is always None – never the field default – so an unset flag does not clobber a value configured in TOML; the real default is applied later by from_options. Booleans use BooleanOptionalAction so --no-<flag> can beat an enabling TOML key; a Literal field becomes a choices-constrained flag; an int field parses as int so TOML and CLI agree on type.

classmethod json_schema() → dict[str, Any]#: Return the JSON Schema for [plugin.myst] (editor autocomplete and validation).

options: Typed configuration schema for the MyST plugin#

`options`: Typed configuration schema for the MyST plugin#