Post-process the Rust AST
On this page
Ferromark parses Markdown into a Document allocated in an arena. The HTML
renderer consumes that document. Afterburner is the optional processing stage
between those steps. In Rust, the ferromark-transforms crate provides an ordered
pipeline of passes over the native AST.
A Remark-like shape, with a different contract
If you know Remark and unified, the staged model will feel familiar: parse content into a syntax tree, run transforms, then produce output. In unified, plugins are composed on a processor; its plugin guide shows that model.
Ferromark shares this processing shape, not the Remark ecosystem. A
TransformPass mutates Ferromark's Rust Document in place. Its API is not
compatible with JavaScript mdast or remark plugins. The parser remains
responsible for Markdown syntax, and the HTML renderer remains responsible for
output. Passes do not add syntax, load Remark plugins, or stringify a Markdown
tree back to Markdown. This is a conceptual comparison, not a compatibility
claim.
Markdown source
→ Ferromark parser
→ arena-backed Document
→ optional ordered TransformPass values
→ optional caller-managed AST additions
→ Ferromark HTML renderer
→ HTML
Add only the passes you need
ferromark-transforms is a separate Rust crate. The core ferromark crate
does not depend on it. Core parsing and rendering do not run transform passes
implicitly; your application opts in by constructing and running a
TransformPipeline. Node.js exposes the built-in passes through an ordered
passes option, but does not expose
the Rust API for arbitrary custom passes.
Each pass is an ordinary Rust type that implements TransformPass. The
pipeline calls passes in the order you add them. A configured pipeline can be
reused for separate documents, but it stores no references to a document or
arena. The custom pass example
shows the complete parse → pass → render flow. The
ferromark-transforms README
documents its helpers and error contract.
The crate also includes an opt-in, language-aware TypographyPass. It converts
prose after parsing while protecting code, math, raw HTML, MDX expressions,
image metadata, and link destinations. Choose one supported language explicitly;
there is no language detection. See the typography guide
for its rules and the matching Node.js option.
use ferromark_transforms::{
TransformPipeline, TypographyLanguage, TypographyOptions, TypographyPass,
};
let options = TypographyOptions::new(TypographyLanguage::English);
let mut pipeline = TransformPipeline::new();
pipeline.add(TypographyPass::new(options));
pipeline.run(&mut document, &context)?;
If a pass returns an error, later passes do not run. A pass may already have changed the document before it fails, so discard or reparse that document; the pipeline does not roll back mutations. The document and all arena-backed nodes must also be dropped before the allocator is reset.
Link GitHub references and expand emoji
GitHubReferencesPass links supported issue numbers, user and team mentions,
commits, and commit ranges. Supply the repository explicitly; the pass never
reads Git remotes or accesses the network. EmojiShortcodesPass replaces known
shortcodes with Unicode emoji using a bundled, pinned dictionary. Unknown
aliases stay unchanged.
use ferromark_transforms::{
EmojiShortcodesPass, GitHubReferencesPass, TransformPipeline,
};
let mut pipeline = TransformPipeline::new();
pipeline.add(GitHubReferencesPass::new("sebastian-software/ferromark")?);
pipeline.add(EmojiShortcodesPass::new());
pipeline.run(&mut document, &context)?;
Both passes preserve protected content such as code, math, existing links, raw HTML, and MDX expressions. See the native transform reference for supported reference forms and differences from Remark plugins. Like typography, these passes run only when added to your pipeline.
Build derived content after transforms
Run passes before asking for data derived from headings, such as the outline. This way, the outline and heading IDs describe the document that will be rendered. Use the same heading-ID settings for the outline and renderer.
Ferromark's optional TOC helper builds a nested list node from that outline. It
does not scan for [[toc]], change the parser, or choose a location. The caller
inserts the returned node wherever it belongs. In a fallible Rust function,
the flow looks like this:
use ferromark::{Allocator, HtmlRenderer, OutlineOptions, Parser};
use ferromark_transforms::build_table_of_contents;
fn render_with_toc(source: &str) -> Result<String, Box<dyn std::error::Error>> {
let allocator = Allocator::for_source_len(source.len());
let mut document = Parser::new(&allocator, source).parse()?;
// Run configured TransformPass values here, before reading the outline.
let outline = document.outline(&OutlineOptions::default());
if let Some(toc) = build_table_of_contents(&allocator, &outline)? {
document.children.insert(0, toc);
}
let mut renderer = HtmlRenderer::new();
Ok(renderer.render(&document))
}
An empty outline produces no node; an entry without an ID is an error. The
helper handles one complete document, not stateful committed or provisional
fragments. Generated nodes use Span::empty(), which means no source range is
available; it is not a general marker for generated content. See the
outline and TOC API guide
for the full API contract and the
TOC placement decision
for the contract.
Use the direct HTML helpers when you only need rendered output. Use AST passes when your application needs to inspect or change the structured document before rendering. For the Rust ownership and rendering workflow, see Build a Rust Content Pipeline.