Ignore: Skip-formatting (“ignore”) comments – the mdformat #53 gap, filled for MyST#
mdformat core has no way to exempt content from formatting. This module adds the family every other formatter ships, as configurable HTML comments (already valid CommonMark, so no new grammar):
<!-- myform-ignore -->preserves the next block verbatim;<!-- myform-ignore-start -->…<!-- myform-ignore-end -->a range;<!-- myform-ignore-file -->the whole file.
Markers act only at the document top level: one nested inside a list item or blockquote is left
as an ordinary comment and does not suppress formatting – acting on it would unbalance the spliced
token tree and re-apply the container’s prefix to the preserved source every run. The marker strings
are configurable via MystOptions.
The mechanism is a markdown-it core rule that runs after block parsing: the tokens of an ignored
span are replaced by a single myst_ignored token carrying the span’s original source, which
Renderer.render_myst_ignored emits verbatim (an html_block carrier would lstrip the first
line and de-indent preserved code). The replacement is ephemeral – internal to one render – and
the emitted markdown is re-parsed fresh on the next run, so formatting stays idempotent (the marker
comments are themselves preserved and re-detected).
Skip-formatting (“ignore”) comments – the mdformat #53 gap, filled for MyST.
mdformat core has no way to exempt content from formatting. This module adds the family every other formatter ships, as configurable HTML comments (already valid CommonMark, so no new grammar):
<!-- myform-ignore -->preserves the next block verbatim;<!-- myform-ignore-start -->…<!-- myform-ignore-end -->a range;<!-- myform-ignore-file -->the whole file.
Markers act only at the document top level: one nested inside a list item or blockquote is left
as an ordinary comment and does not suppress formatting – acting on it would unbalance the spliced
token tree and re-apply the container’s prefix to the preserved source every run. The marker strings
are configurable via MystOptions.
The mechanism is a markdown-it core rule that runs after block parsing: the tokens of an ignored
span are replaced by a single myst_ignored token carrying the span’s original source, which
Renderer.render_myst_ignored emits verbatim (an html_block carrier would lstrip the first
line and de-indent preserved code). The replacement is ephemeral – internal to one render – and
the emitted markdown is re-parsed fresh on the next run, so formatting stays idempotent (the marker
comments are themselves preserved and re-detected).
- myform.Ignore.COMMENT = regex.Regex('\\s*<!--\\s*(?P<body>.*?)\\s*-->\\s*\\Z', flags=regex.S | regex.V0)#
Matches an HTML-comment block whose entire content is a single comment, capturing the inner text.