typst_library/html/
mod.rs

1//! HTML output.
2
3mod dom;
4
5pub use self::dom::*;
6
7use ecow::EcoString;
8
9use crate::foundations::{elem, Content, Module, Scope};
10
11/// Create a module with all HTML definitions.
12pub fn module() -> Module {
13    let mut html = Scope::deduplicating();
14    html.start_category(crate::Category::Html);
15    html.define_elem::<HtmlElem>();
16    html.define_elem::<FrameElem>();
17    Module::new("html", html)
18}
19
20/// An HTML element that can contain Typst content.
21///
22/// Typst's HTML export automatically generates the appropriate tags for most
23/// elements. However, sometimes, it is desirable to retain more control. For
24/// example, when using Typst to generate your blog, you could use this function
25/// to wrap each article in an `<article>` tag.
26///
27/// Typst is aware of what is valid HTML. A tag and its attributes must form
28/// syntactically valid HTML. Some tags, like `meta` do not accept content.
29/// Hence, you must not provide a body for them. We may add more checks in the
30/// future, so be sure that you are generating valid HTML when using this
31/// function.
32///
33/// Normally, Typst will generate `html`, `head`, and `body` tags for you. If
34/// you instead create them with this function, Typst will omit its own tags.
35///
36/// ```typ
37/// #html.elem("div", attrs: (style: "background: aqua"))[
38///   A div with _Typst content_ inside!
39/// ]
40/// ```
41#[elem(name = "elem")]
42pub struct HtmlElem {
43    /// The element's tag.
44    #[required]
45    pub tag: HtmlTag,
46
47    /// The element's HTML attributes.
48    #[borrowed]
49    pub attrs: HtmlAttrs,
50
51    /// The contents of the HTML element.
52    ///
53    /// The body can be arbitrary Typst content.
54    #[positional]
55    #[borrowed]
56    pub body: Option<Content>,
57}
58
59impl HtmlElem {
60    /// Add an attribute to the element.
61    pub fn with_attr(mut self, attr: HtmlAttr, value: impl Into<EcoString>) -> Self {
62        self.attrs.get_or_insert_with(Default::default).push(attr, value);
63        self
64    }
65}
66
67/// An element that lays out its content as an inline SVG.
68///
69/// Sometimes, converting Typst content to HTML is not desirable. This can be
70/// the case for plots and other content that relies on positioning and styling
71/// to convey its message.
72///
73/// This function allows you to use the Typst layout engine that would also be
74/// used for PDF, SVG, and PNG export to render a part of your document exactly
75/// how it would appear when exported in one of these formats. It embeds the
76/// content as an inline SVG.
77#[elem]
78pub struct FrameElem {
79    /// The content that shall be laid out.
80    #[positional]
81    #[required]
82    pub body: Content,
83}
typst_library/html/mod.rs

typst_library/html/
mod.rs
