Skip to main content

Crate merman_doc

Crate merman_doc 

Source
Expand description

§merman-doc

Shared Markdown scanning and static HTML wrapping for merman-rustdoc and the merman rustdoc command. This crate has no renderer, filesystem, or Rust syntax dependency.

scan returns source ranges for Mermaid fences, standalone include_mmd!("path") directives, and individual syntax errors. Callers retain control of file resolution, rendering, diagnostics, and whether to preserve a failed block. visit_blocks additionally accepts cancellation and admission callbacks so command-line callers can stop before collecting or rendering diagrams above their resource limits.

Markdown structure comes from pulldown-cmark. Backtick and tilde Mermaid fences are supported; colon fences are ordinary Markdown text. HTML comments, indented code, other fenced languages, and inline examples do not execute includes. Includes accept one double-quoted path on its own source line. Ordinary escapes such as \\ and \" are decoded with serde_json; raw Rust string literals and Rust-only escapes such as \u{2026} are not supported. Use forward slashes or JSON-compatible escapes when migrating existing macro includes. Unclosed directives produce per-block diagnostics. Existing {mermaid} and comma-separated Mermaid fence info aliases remain supported.

Diagram blocks inside ordered and unordered lists, block quotes, and footnotes retain their container structure, including nested combinations and task list checkboxes. Use explicit indentation and quote markers on standalone include lines. Lazy paragraph continuations without those prefixes produce a diagnostic asking for the missing prefix. The scanner returns an Embedding with each block; use its write_html method to insert generated HTML with the correct first-line and continuation prefixes. html_len counts the exact embedded byte length for callers that enforce output limits. At the end of a complete document, embedding preserves the original trailing line endings without adding blank lines. Use with_trailing_boundary when the scanned source is only a fragment with more documentation supplied separately, such as a group of Rust doc attributes.

write_diagram_html accepts either one SVG or light/dark SVG variants and writes an optional escaped source disclosure. It inserts blank lines around the HTML so adjacent Markdown paragraphs retain their formatting. SVG input must already have been validated by the renderer. Wrapper IDs and source text are HTML-escaped. Multiline SVG is serialized with quick-xml: XML text values and normalized attribute values are retained, while literal newlines become character references. CDATA becomes escaped text and comments are omitted. XML declarations, processing instructions, and DTDs are rejected in multiline inline SVG. This prevents blank lines inside labels or attributes from terminating the enclosing Markdown HTML block.

The Markdown parser itself is synchronous. Cancellation is checked before parsing, between parser events, and while indexing source lines; a single parser operation cannot be interrupted.

§License

Licensed under either the MIT license or the Apache License, Version 2.0, at your option.

Structs§

Block
A replaceable block, including a failed directive that may be kept as source.
Embedding
Markdown container prefixes used to insert a generated HTML block.
Location
One-based position in the original Markdown source.

Enums§

BlockKind
DocError
SvgVariants
SVG inputs must already have passed the caller’s output safety policy.

Functions§

diagram_html_len
Count the exact UTF-8 bytes that write_diagram_html will write.
scan
Find diagram blocks while keeping per-block errors recoverable.
visit_blocks
Visit blocks in source order, with caller-owned cancellation and admission.
write_diagram_html
Write a complete HTML block with Markdown-safe leading and trailing blank lines.