Skip Regions with Pragmas¶
Overview¶
Sometimes you need to prevent snapper from reformatting specific regions: hand-formatted poetry, aligned text, carefully laid-out tables in prose, or any text where line breaks carry meaning.
Use snapper:off and snapper:on pragmas to mark regions that should pass through unchanged.
LaTeX chapter files included with \input can add % snapper:no-preamble so snapper treats the file as body instead of waiting for \begin{document}.
Syntax by format¶
Org-mode¶
Some prose that gets reformatted normally.
# snapper:off
This text will not
be reformatted. Line breaks
are preserved exactly.
# snapper:on
More prose that gets reformatted.
LaTeX¶
Some prose that gets reformatted normally.
% snapper:off
This text will not
be reformatted.
% snapper:on
More prose that gets reformatted.
A \input chapter with no \begin{document} is body by default.
Use % snapper:no-preamble when the file also has \documentclass or you want the flag written down:
% snapper:no-preamble
This sentence is a test. This sentence is also a test.
Markdown¶
Some prose that gets reformatted normally.
<!-- snapper:off -->
This text will not
be reformatted.
<!-- snapper:on -->
More prose that gets reformatted.
reStructuredText¶
A bare line (the same payload as plaintext).
A .. comment is not stripped, so .. snapper:off is not a pragma.
Some prose that gets reformatted normally.
snapper:off
This text will not
be reformatted.
snapper:on
More prose that gets reformatted.
Plaintext¶
Some prose that gets reformatted normally.
snapper:off
This text will not
be reformatted.
snapper:on
More prose that gets reformatted.
Use cases¶
Poetry or verse with intentional line breaks
ASCII art or diagrams in comments
Carefully aligned reference lists
License headers with specific formatting
Text that should match an external source exactly
Nesting¶
Pragmas do not nest.
A snapper:off disables formatting until the next snapper:on.
If the file ends without a snapper:on, the rest of the file passes through unchanged.
Interaction with other features¶
Pragmas take priority over all other parsing. Inside an off region, no sentence splitting, no format-aware parsing, and no abbreviation handling occurs. The pragma comment lines themselves always pass through as structure.
The pandoc path keeps snapper:off / snapper:on in the written output (the reader would otherwise delete them).
Off-region text is shielded so it is not reflowed.
Pass --native to force today’s line parsers.