Rendering HTML

to_html renders a node and its subtree to a compact HTML string. It needs no schema: known Tiptap node and mark types get their usual tags, and options decide what happens to the rest.

let doc = Document::from_json_str(r#"{"type":"doc","content":[
  {"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Title"}]},
  {"type":"paragraph","content":[
    {"type":"text","text":"Read "},
    {"type":"text","text":"the docs","marks":[{"type":"link","attrs":{"href":"https://tiptap.dev"}}]}
  ]}
]}"#)?;

assert_eq!(
    doc.to_html(),
    r#"<h2>Title</h2><p>Read <a href="https://tiptap.dev">the docs</a></p>"#
);

to_html() uses the default options and to_html_with(&opts) takes HtmlOptions. Both exist on Node and Document, and to_html(&node) is the free-function form. Call them on any node, not only the root, to render a fragment.

Default tagsCopy Anchor Link

Marks open in the order they appear in the text node's marks and close in reverse.

A paragraph or heading with a textAlign attribute of left, right, center, justify, start or end gets style="text-align:…". Other values are ignored, so an attribute value cannot inject CSS.

OptionsCopy Anchor Link

HtmlOptions::default() follows the Tiptap conventions above.

let d = doc([
    Node::element("callout").with_child(
        Node::element("paragraph")
            .with_child(Node::text_with_marks("note", [Mark::new("highlight")]))
            .with_child(Node::element("hardBreak")),
    ),
]);

let mut opts = HtmlOptions::default();
opts.node_tags.insert("callout".into(), "aside".into());
opts.mark_tags.insert("highlight".into(), "mark".into());
opts.self_closing = SelfClosingStyle::Xhtml;

assert_eq!(d.to_html_with(&opts), "<aside><p><mark>note</mark><br/></p></aside>");

A tag from node_tags or mark_tags is a plain wrapper: it gets no attributes, except a node's attributes when spread_attrs is on. The tag name is written as given.

Unknown nodes and marksCopy Anchor Link

let d = doc([Node::element("callout").with_child(Node::text_with_marks("hi", [Mark::new("glow")]))]);

assert_eq!(d.to_html(), "hi");

let opts = HtmlOptions {
    unknown_node: UnknownNodePolicy::DataTypeDiv,
    unknown_mark: UnknownMarkPolicy::DataMarkSpan,
    ..Default::default()
};
assert_eq!(
    d.to_html_with(&opts),
    r#"<div data-type="callout"><span data-mark="glow">hi</span></div>"#
);

Spread attributesCopy Anchor Link

With spread_attrs, each remaining attribute whose value is a string, number or boolean becomes an HTML attribute. Attributes the built-in tag already uses (such as a heading's level) are skipped, and so are names with characters other than ASCII letters, digits, -, _ and :. Null, array and object values are skipped. It is off by default because attribute names come from the document.

let d = doc([Node::element("heading").with_attr("level", 3).with_attr("id", "intro").with_text("Hi")]);
let opts = HtmlOptions { spread_attrs: true, ..Default::default() };
assert_eq!(d.to_html_with(&opts), r#"<h3 id="intro">Hi</h3>"#);

HtmlOptions is plain data with Serialize and Deserialize (camelCase field names), so the same options can come from JSON or from the JavaScript package.

Escaping is not sanitizingCopy Anchor Link

Text and attribute values are escaped: &, < and > everywhere, and " inside attributes. That keeps document content from breaking the markup. URLs are written as they are, so a link with a javascript: href survives. If the document comes from an untrusted source, sanitize the HTML before you put it in a page.

let d = doc([Node::element("paragraph").with_text("<script> & \"quotes\"")]);
assert_eq!(d.to_html(), "<p>&lt;script&gt; &amp; \"quotes\"</p>");

Rendering never fails and does not validate the document. For Markdown output, see the Markdown crate.