ferromark-transforms
ferromark-transforms adds an optional, ordered pass pipeline over
Ferromark's native arena-backed AST. The core ferromark crate does not depend
on this package, so parser-only and renderer-only users do not pull it in.
use ;
use ;
use ;
;
let source = "Hello";
let allocator = new;
let mut document = parse?;
let renderer_options = new;
let context = new;
let mut pipeline = new;
pipeline.add;
pipeline.run?;
let mut renderer = with_options;
assert_eq!;
# Ok::
See examples/custom_pass.rs for a pipeline reused
across separate documents and arena resets.
Optional locale-aware typography
TypographyPass changes straight quotes, in-word apostrophes, selected dash
sequences, ellipses, and language-specific spacing after parsing. Choose one of
the fifteen supported language codes explicitly; the pass does not detect or
switch languages. It carries quote pairing across ordinary inline markup and
leaves code, math, raw HTML, MDX expressions, image metadata, link destinations,
and renderer-recognized bare URLs protected.
use ;
let mut pipeline = new;
pipeline.add;
Use with_dashes(false) and with_ellipses(false) to control those changes
independently. The
locale table, output rules, Node.js option, and reference deviations
are documented separately. The parser and renderer never run this pass unless
the caller adds it.
To convert ASCII guillemet digraphs, enable both
ParserOptions::guillemet_digraphs and
TypographyOptions::with_guillemet_digraphs(true). Balanced <<…>> pairs
then use the selected language's primary quotation marks; unmatched markers
stay literal. This pass option is off by default, so ordinary typography runs
do no guillemet pairing work.
GitHub references
GitHubReferencesPass links an explicit supported subset of GitHub references.
Always give it a repository; it never reads package metadata, Git remotes, or
the network. Labels keep their authored text. Local #N and GH-N references,
owner/repo#N, user/team mentions, 7–40 character hexadecimal commits, and commit
ranges are recognized. Existing links, code, math, raw HTML, MDX expressions,
image metadata, destinations, titles, and renderer-recognized bare URLs stay
unchanged.
use ;
let mut pipeline = new;
pipeline.add;
# Ok::
See the native reference decision
for qualification boundaries and differences from remark-github.
Emoji shortcodes
EmojiShortcodesPass replaces known case-sensitive aliases from the pinned
gemoji@8.1.0 dataset with Unicode emoji. Unknown aliases stay as text; the
pass adds no emoticons, spacing, or HTML wrappers. The 1,913-entry map and its
MIT notice are bundled, so no data is downloaded or loaded at runtime.
use ;
let mut pipeline = new;
pipeline.add;
Run pnpm --dir scripts gemoji:data:check to verify that the generated Rust
table matches the pinned source artifact. To intentionally update the data,
review the provenance, change the pinned package and run
pnpm --dir scripts gemoji:data.
Contract
- Passes run in insertion order. The first failure stops later passes and reports its zero-based index, name, and original error.
- A failed pass can have partially changed the document. Discard or reparse that document; the pipeline does not roll changes back.
- Passes may keep configuration and reusable state, but document-specific
references must stay inside
apply. The pipeline keeps no arena references. Passes areSendso a configured pipeline can move to the document's worker; the document and context remain tied to their parsing thread. text_runsgroups adjacentTextsiblings and exposes each segment's source span. It does not cross formatting nodes or choose which nested content is prose; the pass owns that traversal policy.- Replacing text preserves the span being replaced.
replace_text_rangepreserves source spans for unchanged text and gives a replacement the bounding span of the source nodes it covers. Insertions useSpan::empty(); that value is not a distinct provenance marker. - URL ranges are computed only when a pass explicitly asks for them. A
TextRunscans each original text segment independently, using the matcher built from the sameHtmlRendererOptionspassed toTransformContext. Disabled URL autolinking and custom prefixes therefore match the renderer.
Build a caller-placed table of contents
The optional TOC helper turns a core Document::outline into a nested list AST
node. It never scans for a Markdown marker or chooses an insertion location:
let outline = document.outline;
if let Some = build_table_of_contents?
Compute the outline after other passes and use ID settings that match the
renderer. An empty outline produces no node; an outline without heading IDs is
an error. Generated nodes use Span::empty() and describe one complete
document. See the Rust API guide
and the TOC placement decision.