Pandoc Backend¶
Overview¶
The pandoc path is **parse with pandoc, then apply snapper** — not “guess markdown lines like the built-in parsers.”
Pandoc reads the file (any format it supports) into its document AST.
Snapper walks that AST and reflows only prose-bearing nodes (
Para/Plain).Nodes pandoc already classified as structure (
Header,CodeBlock,Table, …) are left alone.The mutated AST is written through an in-process FFI writer when the loaded library exports one, otherwise
pandoc -f json --wrap=preserve.
This is not a splice of the original bytes.
That is how snapper can format everything pandoc can read (typst, asciidoc, docx, html, …) without inventing per-format line heuristics.
How to run step 1 (same step-2 walker):
Auto —
--pandoc-backend auto(default): prefer in-process FFI whenlibsnapper_pandocloads, else CLI.
This amortizes the GHC RTS for parse.
The shipped library is reader-only, so the writer still needs pandoc on PATH unless that library exports a writer (no silent spawn).
CLI —
--pandoc-backend cli:pandoc -t json(full reader set of the installed binary).
Explicit error if pandoc is missing.
FFI —
--pandoc-backend ffi: requirelibsnapper_pandoc(explicit error if missing).
Writer still needs pandoc on PATH when the library has no writer.
Requirements¶
**CLI backend.**
Pandoc 2.x or 3.x on PATH.
The CLI default is the native line parsers.
--use-pandoc, or use_pandoc = true in .snapperrc.toml, opts into pandoc.
With --use-pandoc, a missing or failing pandoc is an explicit error (no silent all-prose).
--native is accepted and selects the native parsers.
Markdown on the pandoc path is read and written as gfm.
A render mismatch leaves the input unchanged and warns on stderr.
A list item or blockquote at the end of the file still splits when the final newline is missing.
**Writer.**
The library libsnapper_pandoc is reader-only.
The write step still needs pandoc on PATH (help and errors say so).
A library that exports snapper_pandoc_write stays in-process for write too.
**FFI backend (dynamic).**
Build native/snapper-pandoc, set SNAPPER_PANDOC_LIB to libsnapper_pandoc.so (or put it on the search path).
A missing library with --pandoc-backend ffi errors with pandoc FFI library unavailable (fail-closed; never silent all-prose).
**FFI backend (co-linked / one binary).**
Feature pandoc-colink is a build path: produce libsnapper_pandoc.a with native/snapper-pandoc/build-static.sh (ghc -staticlib), then Cargo absorbs that archive into a single snapper executable (--gc-sections).
No SNAPPER_PANDOC_LIB discovery and no multi-hundred-MB libHS* RUNPATH graph.
cd native/snapper-pandoc && ./build-static.sh
export SNAPPER_PANDOC_LIB_DIR=$PWD/lib
cargo build --release --features "cli,pandoc,pandoc-colink"
snapper --use-pandoc --pandoc-backend ffi paper.md
See native/snapper-pandoc/README.md.
Usage¶
# Default: native line parsers
snapper paper.md
# Require pandoc (error if missing). Markdown is read and written as gfm.
snapper --use-pandoc paper.md
snapper --use-pandoc --pandoc-backend auto paper.md
snapper --use-pandoc --pandoc-backend cli guide.adoc
snapper --use-pandoc --pandoc-backend ffi paper.md
snapper --use-pandoc paper.typ
# Accepted no-op: the default is already native
snapper --native paper.md
The CLI default is the native line parsers.
--use-pandoc, or use_pandoc = true in .snapperrc.toml, requires the pandoc path (explicit error if FFI and pandoc are missing).
--native is accepted and selects those same native parsers.
The writer still needs pandoc on PATH unless the library exports a writer.
**Speed.**
Warm in-process FFI parse is a few times native cost; a cold pandoc CLI process reloads the GHC RTS (tens of ms).
The writer is that CLI spawn unless the FFI library exports a writer — it is never a surprise.
Snapper also caches pandoc JSON ASTs by content hash (memory + disk under $XDG_CACHE_HOME/snapper/pandoc-ast).
Re-formatting the same source skips pandoc parse.
Disable with SNAPPER_PANDOC_CACHE=0; override dir with SNAPPER_PANDOC_CACHE_DIR.
When to use pandoc vs built-in parsers¶
**Built-in** (CLI default): fast, source-oriented parsers for Org / LaTeX / Markdown / RST (e.g. full ATX lines as structure).
**Pandoc** (
--use-pandocoruse_pandoc = true): structure from pandoc’s model and coverage of formats without a built-in parser.
The two paths are different pipelines, not two ways to fake the same source lines.
Limitations¶
Pandoc’s reader deletes comments (RST
..comments, HTML comments) and thereforesnapper:off/snapper:on.--use-pandocshields RST..comments andsnapper:off/snapper:onso the written output still contains that text and exits 0.Other HTML / Org / LaTeX comments that are not snapper pragmas may still be dropped.
Round-trip is through the AST (not a perfect source-preserving rewrite of every markup character)
FFI library is optional; wasm/editor bundles do not embed GHC/pandoc
CLI pandoc versus editor native is the contract: the CLI default is native;
--use-pandocopts into pandoc; VS Code, Obsidian, Word, wasm, and LSP stay on native parsers.