Round trip
In html, markdown and yaml modes the output is your input with a few substring replacements applied, and nothing is re-serialised.
In html, markdown and yaml mode, transform returns the input source with a set of disjoint substring replacements applied at recorded offsets. No other byte of the input changes.
This is stronger than "unchanged when nothing needs fixing". The parser, where there is one, is used only to find where the prose is. It is then discarded. The document is never rebuilt from a parse tree, so nothing a serialiser would normalise can change.
How it works #
The span model records, for every processable span, where it starts and ends in the original source. The rules produce edits against the joined text; each edit is mapped back to those offsets. The result is the original source with only those stretches replaced.
yaml mode uses no parser at all. It scans the text to find the values of the keys you name, so there is nothing to decode and re-emit.
Examples #
An HTML document. Only the prose changes. The upper-case tags, the unquoted and single-quoted attributes, the and & references, the self-closing <BR/>, the doctype, the comment, the pre block and the script are returned as they were written:
Input
Output
A Markdown document. The list markers, emphasis delimiters, link destination and title, inline code and indented code block are untouched. The trailing newline is kept:
Input
Output
What is preserved #
- Attribute quoting (
class=foo,class='foo'andclass="foo"all stay as written), attribute order, duplicate attributes and whitespace inside tags. - Tag name case, and self-closing and void forms (
<br>,<br/>,<br />). - Character references:
&does not become&, and does not become U+00A0. A bare&stays a bare&. - The doctype, comments and trailing whitespace.
- Markdown list markers, emphasis delimiters, heading style, table alignment, hard-break spaces and line endings.
- YAML quoting style, indentation, anchors, tags and block scalar chomping indicators.
- Malformed input. Unclosed tags, stray
<and mismatched nesting are not repaired. Parser error recovery only affects where prose is found, never what is written out.
Edge cases #
- MDX can fail to parse. Markdown with
dialect: "mdx"embeds JavaScript, and a broken JSX element or expression raisesPOLYTYPO_MALFORMED_INPUTinstead of producing output. See Error codes. - Edits that would change structure are dropped. An edit that would add a space at the very start or end of a span is discarded, so a markup boundary is never made to touch new whitespace. See the span model.
Related #
Normative text: spec/rules/modes.md.