Crate markdown_syntax

Expand description

§markdown-syntax

A no_std + alloc Rust crate that parses Markdown source into an owned AST and writes the AST back as Markdown, keeping the source of every block you did not change — with opt-in, safe-by-default HTML rendering behind the html feature.

§At a glance

AST-first — parse returns an owned enum tree over alloc; the output verbs live on the Document you hold.
Tolerant — problems are collected as diagnostics, never thrown; parse is infallible.
The source is the only truth — a parsed Document keeps its source, and writing it back reuses the bytes of every unchanged block.
One syntax — CommonMark + GFM + footnotes + alerts + math + frontmatter + wikilinks + directives + == highlight + shortcodes + # tags, with nothing to configure.
Lean core — zero runtime dependencies, no_std + alloc, MSRV 1.82.

§Install

cargo add markdown-syntax

For the opt-in HTML renderer:

cargo add markdown-syntax --features html

Or in Cargo.toml:

[dependencies]
markdown-syntax = "0.3"

§Quickstart

use markdown_syntax::parse;

// `parse` is infallible and returns a `ParseOutput { document, diagnostics }`.
let output = parse("# Title\n\nHello *world*.");
assert!(output.diagnostics.is_empty());

// Writing an unedited parse returns its source (this is the fallible step).
assert_eq!(output.document.to_markdown()?, "# Title\n\nHello *world*.");

// Without its source, the document is written as canonical Markdown.
let markdown = output.document.without_source().to_markdown()?;
assert_eq!(markdown, "# Title\n\nHello *world*.\n");

parse is infallible — the output verbs live on the Document you hold.

§Common tasks

parse reads a document and parse_inline one block’s inline content, with the same syntax. When you need to read diagnostics, walk the tree, edit and write back, or render HTML, each task is one small snippet below.

Walk the AST
Handle diagnostics
Edit and write back
Customize serialization
Parse one block’s inline content
Source positions (optional)
Build an AST by hand

§Walk the AST

use markdown_syntax::{parse, Block, Inline};

let document = parse("Hello *world*.").document;

for block in &document.children {
    if let Block::Paragraph(paragraph) = block {
        for inline in &paragraph.children {
            if let Inline::Text(text) = inline {
                assert_eq!(text.value, "Hello ");
                break;
            }
        }
    }
}

document.children is a Vec<Block>; block content (like Paragraph.children) is a Vec<Inline>. See the ast module, Block, and Inline.

§Handle diagnostics

use markdown_syntax::{parse, DiagnosticSeverity};

// Problems are collected, never thrown.
let output = parse(":::note\nunclosed container");
for diagnostic in &output.diagnostics {
    let _ = (diagnostic.severity, diagnostic.code, diagnostic.span, &diagnostic.message);
    if diagnostic.severity == DiagnosticSeverity::Error {
        // handle an error-severity diagnostic
    }
}

span is Option<Span> because a hand-built node may lack a source location. Parser diagnostics, AST validation, and serializer/HTML pre-validation are three separate domains that share one Diagnostic type.

§Edit and write back

use markdown_syntax::prelude::*;

let source = "|a|b|\n|-|-|\n\n*  x\n\n\n# T #";
let mut document = parse(source).document;

// An unchanged block is written as its source, with the bytes around it.
assert_eq!(document.to_markdown()?, source);

// An edited or new block, one without the spans of the block the source
// parses to there, is written as canonical Markdown. The second blank line
// before the heading is a `BlankLine` node, and is kept.
document.children[1] = Paragraph::new([Text::from("y")]).into();
assert_eq!(document.to_markdown()?, "|a|b|\n|-|-|\n\ny\n\n\n# T #");

A block keeps its source when it corresponds to the block the source parses to at the same span: it equals that block, spans included, except that a leaf built from text (below) counts when its text is that leaf’s inline source. Where its source would read differently in its new place, as an unclosed fence before a new block would, it is written canonically too.

§Customize serialization

use markdown_syntax::{parse, BulletMarker, LineEnding, SerializeOptions};

// `SerializeOptions` is #[non_exhaustive]: mutate a default rather than using a
// struct literal.
let mut options = SerializeOptions::default();
options.line_ending = LineEnding::CrLf;
options.final_newline = false;

let markdown = parse("# Title").document.without_source().to_markdown_with(&options)?;
assert_eq!(markdown, "# Title");

// List-marker and fence options are `None` by default, keeping the marker
// each node records; `Some` writes every list or fence with the one given.
let mut options = SerializeOptions::default();
options.bullet = Some(BulletMarker::Dash);
assert_eq!(parse("* a").document.without_source().to_markdown_with(&options)?, "- a\n");

// Each node is written in the spelling it records: `_` emphasis stays `_`,
// an escape stays an escape, and a literal autolink stays bare.
let document = parse("_a_ \\*b\\* https://example.com").document.without_source();
assert_eq!(document.to_markdown()?, "_a_ \\*b\\* https://example.com\n");

Options apply to the Markdown the writer writes, not to reused source; the examples above drop the source to show them.

Because SerializeOptions is #[non_exhaustive], external code cannot struct-literal-construct it (even with ..Default::default(), E0639) — mutate a default() instead.

The serializer only renders: it writes text, escapes, and character references as the AST records them and never parses its own output. A hand-built Text("*a*") is written *a*, which reads back as emphasis; build literal punctuation with Escape nodes instead. A hand-built tree that no Markdown can express — a link inside a link, say — fails validation, and to_markdown returns SerializeError::InvalidDocument with the diagnostics.

§Parse one block’s inline content

use markdown_syntax::prelude::*;

let document = parse("> a [*b*][r]\n> c\n\n[r]: /u").document;

// The text the parser read for the paragraph in the block quote, and where
// each of its offsets sits in the source.
let leaf = document.inline_source(&NodePath::from([0, 0])).unwrap();
assert_eq!(leaf.text, "a [*b*][r]\nc");
assert_eq!(leaf.to_source(11), 15);

// Parsing that text again, with the document's definitions, gives the
// paragraph's inlines; no block rule applies, so `# c` would stay text.
let inline = parse_inline(&leaf.text, &Definitions::of(&document));
assert!(matches!(inline.inlines[1], Inline::LinkReference(_)));

parse_inline spans are byte ranges into the text; InlineSource::span_to_source maps them to the document’s source. Document::leaf_sources returns the inline source of every leaf (paragraphs, headings, table cells, and directive labels) in one pass.

§Build a leaf from its text

use markdown_syntax::prelude::*;

let source = "- a  `` b ``\n";
let mut document = parse(source).document;
let definitions = Definitions::of(&document);

// A leaf built from text keeps it and is written as it, so an editor that
// holds each leaf as text writes back what the user typed.
let Block::List(list) = &mut document.children[0] else { unreachable!() };
let Block::Paragraph(paragraph) = &mut list.children[0].children[0] else { unreachable!() };
let span = paragraph.meta.span;
*paragraph = Paragraph::with_source("a  `` c ``", &definitions).0;
paragraph.meta.span = span;
assert_eq!(document.to_markdown()?, "- a  `` c ``\n");

The text counts while the leaf’s inlines are the ones it reads as; a leaf whose inlines were edited afterwards is written from them.

§Source positions (optional)

use markdown_syntax::{parse, LineIndex};

let source = "# Title\n\nHello.";
let document = parse(source).document;
let index = LineIndex::new(source);

// Spans are absolute, half-open UTF-8 byte ranges; `None` for hand-built nodes.
if let Some(first) = document.children.first() {
    if let Some(span) = first.span() {
        let (start, end) = index.span(span);
        // 1-based line/column.
        assert_eq!(start.line, 1);
        assert_eq!(start.column, 1);
        let _ = (span.start, span.end, span.len(), end.line, end.column);
    }
}

Spans are absolute half-open UTF-8 byte ranges, None for hand-built nodes. LineIndex turns a Span into 1-based LinePosition line/column.

§Build an AST by hand

The prelude imports the common surface in one line:

use markdown_syntax::prelude::*;

let document = Document::new(vec![
    Heading::new(1, [Text::from("Title")]).into(),
    Paragraph::new([Text::from("hello")]).into(),
]);
// Hand-built nodes carry no span.
assert_eq!(document.children[0].span(), None);
assert_eq!(document.to_markdown().unwrap(), "# Title\n\nhello\n");

// Text is written as it is; `Escape` writes a literal punctuation char.
let escape = |value| Inline::from(Escape { meta: NodeMeta::default(), value });
let literal = Document::new(vec![Paragraph::new([escape('*'), Text::from("a").into(), escape('*')]).into()]);
assert_eq!(literal.to_markdown().unwrap(), "\\*a\\*\n");

§HTML rendering (opt-in)

The HTML renderer ships behind the non-default html feature and is safe by default: it validates the AST first, escapes raw HTML, blanks dangerous link/image protocols, and disables task-list checkboxes.

cargo add markdown-syntax --features html

// Requires `--features html`; the default doctest build has no html feature,
// so this block is `rust,ignore`.
use markdown_syntax::{parse, HtmlOptions, HtmlError, SafeRawHtmlForm};

let document = parse("# Hi\n\n<script>alert(1)</script>").document;

// Default is safe: raw HTML is escaped, dangerous link/image protocols blanked.
let safe: Result<String, HtmlError> = document.to_html();
assert!(safe.is_ok());

// `HtmlOptions` is #[non_exhaustive]: mutate a default to opt into raw HTML.
let mut options = HtmlOptions::default();
options.allow_dangerous_html = true;
options.safe_raw_html_form = SafeRawHtmlForm::OmitPlaceholder;
let _ = document.to_html_with(&options);

See HtmlOptions. docs.rs builds with the html feature enabled, so the renderer’s API is fully documented there.

§WebAssembly and JavaScript

The markdown-syntax-wasm crate in wasm/ builds the parser for wasm32-unknown-unknown with a zero-dependency C ABI, and wasm/js/index.js (types in index.d.ts) wraps it with no npm dependency: parse (with every leaf’s inline source), parseInline, inlineSource, and toMarkdown (which takes a leaf as its source text), with every span in UTF-16 code units. It is not published; build it with

cargo build -p markdown-syntax-wasm --target wasm32-unknown-unknown --profile wasm

§Syntax reference

parse recognizes one fixed syntax:

Family	Constructs
CommonMark	everything, including raw HTML and indented code
GFM	tables, task list items, `~~` strikethrough, literal autolinks (`http://`, `https://`, `www.`, emails, `mailto:`, `xmpp:`), alerts
Footnotes	`[^id]` references and definitions, inline `^[note]`
Extensions	frontmatter (`---` / `+++`), inline and block math, wikilinks (`[[target\|title]]`, embeds `![[x]]`), `==` highlight, gemoji shortcodes (`:tada:`), `#` tags (`#ai/agents`), `:name` / `::name` / `:::name` directives, `<details>` HTML containers

Where one node has more than one spelling, the parse records it: Emphasis and Strong record * or _, and Autolink records an angle-bracket or a literal autolink; Link is the inline [text](destination) form. A node stores each written fact once: an Autolink derives its destination() from its text, a CharacterReference decodes its value() from the reference, and a CodeInline holds only its value, its fence chosen when written.

Cargo features:

Feature	Default	What it adds
`default`	`[]` (empty)	Byte-stable `no_std + alloc` core: parser, AST, serializer, validation, `Span`/`LineIndex`, prelude. Zero runtime deps.
`html`	off	Opt-in, additive, safe-by-default `to_html` / `to_html_with` and the `html` module. Stays `no_std + alloc`, zero runtime deps.

§How it works

AST-first public API — parse produces an owned Document holding its source; parser event streams and internal block operations are private, not v1 compatibility surfaces.
Owned enum tree over alloc types.
Optional source spans — half-open absolute byte ranges on every node, None for hand-built nodes; line/column derived via LineIndex.
Tolerant by default — diagnostics are collected, not thrown.

§Scope & limitations

In scope — the one syntax in the syntax reference. Subscript, superscript, insert, spoiler, underline, description lists, and MDX are not recognized: __a__ is strong, and the rest stay text or raw HTML.

Not in the default build: HTML rendering or sanitization, and syntax highlighting. A block you edit is written in canonical Markdown, so its authoring style is kept only as far as the AST records it. Directives (:name / ::name / :::name) are their own family and are never MDX.

Parsing, inline parsing, serialization, HTML rendering, and validation take linear time and bounded stack on any input; nesting past fixed limits stays literal text.

The full behavior contract — syntax, serialization, validation, HTML rendering, and the cost limits — lives in docs/specs/.

§Compatibility

no_std + alloc (crate root is #![no_std] + extern crate alloc). Default features are empty; the opt-in html feature also stays no_std + alloc. Zero runtime dependencies. MSRV 1.82 (edition 2021).

§Contributing & conformance

Tests live in tests/. AST→HTML correctness is measured against vendored CommonMark/GFM oracles; observe the current numbers with cargo test --features html --test html_conformance -- --nocapture.

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use diagnostic::Diagnostic;
pub use diagnostic::DiagnosticCode;
pub use diagnostic::DiagnosticSeverity;
pub use html::HtmlError;
pub use html::HtmlOptions;
pub use html::SafeRawHtmlForm;
pub use html::TasklistAttrOrder;
pub use parse::parse;
pub use parse::parse_inline;
pub use parse::Definitions;
pub use parse::InlineOutput;
pub use parse::InlineSource;
pub use parse::InlineToken;
pub use parse::ParseOutput;
pub use parse::TokenRole;
pub use serialize::BulletMarker;
pub use serialize::LineEnding;
pub use serialize::OrderedDelimiter;
pub use serialize::SerializeError;
pub use serialize::SerializeOptions;
pub use span::LineIndex;
pub use span::LinePosition;
pub use span::Span;
pub use ast::*;

Modules§

ast: The owned Markdown AST that parse() produces and Document::to_markdown/to_html consume. Every node carries a NodeMeta with an optional source Span. Block and Inline are the two node enums; everything else is a concrete node struct or a small enum describing a node’s variant.
diagnostic: The unified Diagnostic type shared by the parser, AST validation, and the serialize/HTML pre-validation.
html: AST to HTML rendering.
parse: Markdown source to AST. The entry point is the free parse function, which reads the crate’s one syntax. Parsing is tolerant: problems are collected as Diagnostics rather than aborting.
prelude: Common imports for working with markdown-syntax: use markdown_syntax::prelude::*; brings the AST, diagnostics, the parse entry points, and serialize/span types (plus the HTML renderer under the html feature) into scope.
serialize: AST to Markdown. The verbs live on Document (to_markdown / to_markdown_with); SerializeOptions tunes the output style. The document is validated first, so serialization can fail with a SerializeError.
span: Source locations: byte-offset Spans and their LineIndex translation into human-readable line/column LinePositions.
validate: AST validation: Document::validate walks the tree and reports each invalid or unsupported node shape as a Diagnostic. Serialization and HTML rendering run this first and refuse an invalid document.