Build a Rust Content Pipeline

Use the direct HTML helpers for owned output. Use the arena AST when you need metadata, source spans, visitors, or custom rendering.

Parse once, inspect, then render

use ferromark::{Allocator, HtmlRenderer, HtmlRendererOptions, Parser, ParserOptions};

let source = "---\ntitle: Installation\n---\n# Installation\n";
let allocator = Allocator::for_source_len(source.len());
let document = Parser::with_options(
    &allocator,
    source,
    ParserOptions { front_matter: true, ..ParserOptions::gfm() },
).parse().unwrap();
assert_eq!(document.front_matter.as_ref().unwrap().value, "title: Installation\n");
let html = HtmlRenderer::with_options(HtmlRendererOptions {
    sanitize: true,
    ..HtmlRendererOptions::default()
}).render(&document);
assert!(html.contains("Installation"));

The front-matter value borrows the original source. Deserialize its raw YAML- or TOML-style contents with your chosen library. The source and allocator must outlive the document. Drop all documents before resetting an allocator.

AST visitors expose nested nodes and source spans. Use the renderer's collect_heading_text and slugify_heading helpers when building heading-based tooling, and account for explicit IDs and duplicate suffixes. The application owns where heading-based navigation appears; the optional outline extension provides the structured data for that integration.

To change the document between parsing and rendering, see Post-process the Rust AST for the optional ordered transform pipeline and caller-placed table of contents.

Analyze the parsed document

Call document.collect_references(source) to inventory links and assets, document.extract_text(&options) to get static text and final JSX heading sections, or document.project_markdown(source, &options) to export original static Markdown with omission diagnostics. Each method runs only when called. Keep the matching original source for operations that take it explicitly.

See document analysis for Rust and Node examples, source-range rules, and reference snapshots around mutable native passes.

Append HTML to an existing string

let mut output = String::from("<main>\n");
ferromark::to_html_into("First document.", &mut output).unwrap();
ferromark::to_html_into("Second document.", &mut output).unwrap();
output.push_str("</main>\n");
assert!(output.starts_with("<main>\n<p>First document.</p>"));

These functions append and retain output capacity. A parse error leaves the string unchanged. Every call creates a temporary arena and renderer, with independent heading, reference, and footnote state. For explicit scratch reuse, retain HtmlRenderer and reset an Allocator between documents.

Handle parser errors

The helpers and Parser::parse() return Result. Exceeding the configured block-nesting limit returns an error; the default limit is 100. Keep a finite limit for untrusted input. See the Rust API guide for ownership and output contracts.

Next: custom HTML hooks.