socketry-markdown

A CommonMark-compliant Markdown parser for Rust with an AST, extensions, and HTML and Markdown renderers. It is based on markdown-rs and adds Socketry's AST helpers and renderer APIs.

Install

cargo add socketry-markdown

The library supports Rust 1.73 and later.

Render HTML

For direct conversion from Markdown source to HTML:

let html = socketry_markdown::to_html("## Hello, *world*!");
assert_eq!(html, "<h2>Hello, <em>world</em>!</h2>");

Enable GFM constructs with Options::gfm():

use socketry_markdown::{to_html_with_options, Options};

let html = to_html_with_options("* [x] done", &Options::gfm()).unwrap();

Work with the AST

Parse to a syntax tree when you need to inspect or transform Markdown:

use socketry_markdown::{to_mdast, ParseOptions};

let document = to_mdast("# Introduction\n\nHello, *world*!", &ParseOptions::default()).unwrap();
assert_eq!(document.text_content(), "IntroductionHello, world!");

Nodes provide traversal, text extraction, code-fence information, heading lookup, and child or section editing. extract_children() returns a Fragment that can be cloned, rendered, or serialized on its own.

Use HTMLRenderer or a custom Renderer to render an AST. Serialize nodes and fragments back to Markdown with Node::to_markdown():

let markdown = document.to_markdown();
assert!(markdown.starts_with("# Introduction"));

Extensions

The parser supports CommonMark, GFM, MDX, frontmatter, and math constructs. HTML output escapes raw HTML and omits MDX expressions by default. See the API documentation for parser options, renderer configuration, and AST types.

Agent Context

This crate publishes context files for coding agents. Configure Bake Agent Context in your private bake/ crate, then run cargo bake agent:context:install --package socketry-markdown to install them in .agents/context/ and update agents.md.

Releases

See releases.md for the full release history.

v0.1.0

• Add AST renderers for HTML and Markdown, including Markdown serialization on nodes and fragments.
• Add fragment extraction, heading helpers, and parser fixes from the Socketry fork.
• Adopt shared Socketry testing, documentation, and release automation.

See Also

• socketry-markdown — CommonMark compliant markdown parser in Rust with ASTs and extensions

• markdown-rs — the upstream parser.

• CommonMark — the Markdown specification.

Contributing

Please open an issue or pull request on GitHub.