HTML Export

[Nitwel]

This is all very much my draft notes currently but will be worked upon in the comming days, so take everything with a grain of salt.

tl;dr This is looking really promising already in terms of translatability, the main callenge here will likely be the rewrite of the Layout process into separate steps as discussed.

Comparison Typst => HTML

How easy we could convert most functions into a HTML/CSS counterpart.

Text

• #lorem() -> #text
• #emph -> <em>
• #linebreak -> <br>
• #lower -> <span class="lower"> or similar with text-transform: lowercase
• #overline -> <span class="overline"> with text-decoration: overline
• #raw -> <code> with syntax highlighting done over a <div> instead (possibly highlight.js)
• #smallcaps -> <span class="smallcaps">
• #smartquote -> #text
• #strike -> <s>
• #strong -> <strong>
• #sub -> <sub>
• #super -> <sup>
• #text -> <span>
• #underline -> <span class="underline"> with text-decoration: underline
• #upper -> <span class="upper"> or similar with text-transform: uppercase

Math

Good sauce: https://fred-wang.github.io/TeXZilla/

• accent -> <mover>
• attach -> <munderover> / <msubsup>
• scripts -> <msubsup>
• limits -> <munderover>
• binom -> <mrow><mo>(</mo><mfrac linethickness="0px"><mi>n</mi><mi>k</mi></mfrac><mo>)</mo></mrow>
• cases -> <mrow><mo>{</mo><mtable columnalign="left left" displaystyle="false"></mtable></mrow>
• equation -> <math>
• frac -> <mfrac>
• lr -> <mrow> with <mo>
• mat -> <mtable>
• root -> <mroot> and <msqrt>
• round -> Same as lr
• styles -> with css
• op -> <mo> or <mi>
• under/over -> <munderover>
• variants -> #text
• vec -> <mtable>

Layout

• #align -> <span class="center"> with text-align: center
• #block -> <div>
• #box -> <div class="box"> with display: inline-block
• #list -> <ul>
• #colbreak -> maybe possible with css break-before: ...
• #columns -> possible with column-count: 2
• #grid -> <div class="grid"> with display: grid and so on
• #hide -> either with opacity: 0 or using a <div> with a fixed width
• #measure -> maybe possible with js?
• #move -> with position: relative; top: y, left: x
• #enum -> <ol> tbh, the name could maybe be improved
• #pad -> with padding: 10pt 2pt ...
• #page -> Doesn't make sense in context of web media
• #pagebreak -> Same as #page
• #par -> <p>
• #parbreak -> beginning of new <p>
• #place -> with position: absolute; top: ...
• #repeat -> Could maybe be possible with width: 100%; overflow: hidden but very hacky
• #rotate -> with transform: rotate(...)
• #scale -> with transform: scale(...)
• #h -> possibly with position: inline-block; width: ...
• #v -> same as #h but with height instead of width
• #stack -> with display: flex
• #table -> <table>
• #terms -> <dl>

Visualize

Easily possible using SVG's

• #circle -> <circle>
• #ellipse -> <ellipse>
• #image -> <image>
• #line -> <line>
• #path -> <path>
• #polygon -> <polygon>
• #rect -> <rect>
• #square -> <rect>

Meta

• #bibliography -> Likely with <a href="#el-id"> but has to be looked into
• #cite -> same as #bibliography
• #counter -> #text
• #document -> should be used to insert meta information into the HTML Document.
• #figure -> <figure>
• #heading -> <h1> /<h2> / ...
• #link -> <a>
• #locate -> Doesn't make much sense in the context of web media / possibly with JS
• #numering -> #text
• #outline -> #text
• #query -> can be ignored
• #ref -> <a>
• #state might be ignored
• #style -> possibly can be ignored

[Enivex]

#repeat -> Doesn't make sense in the context of web media

I fail to see why that is

#hide -> with opacity: 0

Documentation says "It may also be useful to redact content because its arguments are not included in the output.", so simply using opacity is not an option

#page -> Doesn't make sense in context of web media
#pagebreak -> Same as #page

It should at least be possible to get separate pages for chapters/sections, with a menu for navigation.

[ararunaufc]

I'll always vote in favor of semantic tags. That means em and strong instead of the alternatives, for example.

There are some more tags that may be used with this in mind, like section, figure...

[lingo]

Re this:

#page -> Doesn't make sense in context of web media
#pagebreak -> Same as #page

There are CSS page-break and @page properties which could be useful (mostly if other tools are going to process the HTML in some way).

Providing for something like<br class="page-break"> would be useful, at least, or as mentioned by @ararunaufc , using semantic tags like <section class="page"> might be better?

[Nitwel]

Thanks for the comments, updated the comparison above! ❤️

On the note of pages, we could have some form of metadata in the HTML document noting down, where we want to do a page-break, though it might miss the point as exporting to a printable document should go through the PDF export directly instead of exporting it to html and then printing that.

But yes, we can look into supporting that too.

[laurmaedje]

Math should use MathML!

[ararunaufc]

Math should use MathML!

That would be ideal in principle, but maybe not great in practice...

Quoting MDN:

the subset focusing on semantics has never been implemented in browsers while the subset focusing on math layout led to incomplete and inconsistent browser implementations.

Maybe MathML Core, but I don't know how that would work out.

Note: It is highly recommended that developers and authors switch to MathML Core, perhaps relying on other web technologies to cover missing use cases.

[Nitwel]

We can definitely focus on using MathML Core, my current translation should also only contain MathML Core elements as far as I'm aware.

[reknih]

Hey! Thanks for this issue. I wanted to chip in with a few thoughts here:

• emph and strong are intended as semantic functions and should be translated to em and strong tags respectively.
• Arguably, strike should be translated to the s tag. However, the semantics of s are quite narrow and there is also the del element to cover other semantic cases. Because there is no alternative way of achieving a "non-semantic" strikethrough in Typst like there is for emph and strong, I can be swayed either way as to whether these functions should result in a semantic tag or CSS.
• document shall not be ignored. Its title property should set the title tag's content and the author property might be used to populate Open Graph meta tags
• state should not be ignored.
• hide must keep its content private. A solution that @laurmaedje will likely hate me for is to measure its content's dimensions using the normal print layout code paths and then create a inline-block of these dimensions. This solution does not guarantee that the space reserved is the same as if the user agent had rendered hide's contents. Alternatively, hide could be ignored for the moment.

In general, you carry over quite a bit of styling! We should ask ourselves what the goal of HTML output will be: Is it to strive for a pixel-perfect reproduction of the PDF or to produce a document that feels "web native" and can easily be styled with downstream CSS or be used as an artifact in i.e. a static site generator. Or do we want something in-between (eBooks)?

The answer to these questions should inform the design with respect to the more invasive layout functions like move and place. They are built a series of fixed-height viewports instead of a continuous one, so does applying them to HTML output make sense? How many of the text styles should be applied as CSS? Should a Typst document be able to conditionally decide what to do depending on the export target? It is true that we could also conditionally apply a lot of these styles only when the HTML document is printed with media queries, the CSS paged media module, or ePub extensions.

I, personally, think that Typst's HTML output should be more semantic than a pixel-perfect reproduction of the PDF. However, I do not have an opinion yet to the extend we should "bake in" styles as CSS and apply functions like place.

[Nitwel]

Updated emph, strong, strike and document.

On the note of state: As far as I understood that feature, it will compile into text or something else and won't matter for the HTML export. I used #text in those cases, meaning, HTML export doesn't have to worry about it.

I'm definitely on par with keeping the outputed HTML file as semantic as possible so I propose the following balance between Semantics and Styling.

1. If there is a 1 to 1 translation between Typst and HTML, we use it.
   like emph and <em>
2. Typst functions that have no direct translation but which functionallity can be reproduced in HTML, should at least share exact behaviour.
   like #parbreak and starting a new paragraph in html or #lower with a class that sets it's contents to lowercase
3. For Typst functions that will have different behaviour depending on their context, at the moment either PDF or HTML, we will implemend something like media queries in css, that allow to apply different functionallity depending on their environment.
   This could look something like:

if context == "HTML" {
  #place(...)
} else {
  #place(...)
}

4. Functions that are not possible when having the layout phase after the export phase should be ignored for now and revisited later as their only solution would have to be hacked into HTML and thus need further in depth discussion on what we should do in each case.
   like #hide or #measure

Let me know if that aligns with your thoughts on an HTML export or if I should think this through furhter.

[laurmaedje]

On the note of state: As far as I understood that feature, it will compile into text or something else and won't matter for the HTML export.

That's correct. There are some things in your list which are already resolved by the time HTML export will start, including query, state, and counter.

[ararunaufc]

3. For Typst functions that will have different behaviour depending on their context, at the moment either PDF or HTML, we will implemend something like media queries in css, that allow to apply different functionallity depending on their environment.

Personally, I would prefer this to be something to do outside of the document, and I would avoid making the document "know" about existing environment options.

What I mean is that the document would only describe what it would like to do and something else would provide the how. (Not a proposal, but picture something like CSS custom properties that can only be set outside of their usage.)

[bluebear94]

Note that there are multiple HTML tags that have the same style by default but different semantic connotations: cite, em, and i for italics and b and strong for bold. Perhaps Typst could pick a reasonable default (namely, em and strong) but provide commands for the other tags for those who care about the distinction.

[Enivex]

Note that there are multiple HTML tags that have the same style by default but different semantic connotations: cite, em, and i for italics and b and strong for bold. Perhaps Typst could pick a reasonable default (namely, em and strong) but provide commands for the other tags for those who care about the distinction.

The semantic distinction is important for accessibility is not?

[drewcassidy]

I think his would be very useful. The typst language looks perfect for a static site builder, by being both a templating language and a markup language all in one

[drewcassidy]

Im currently investigating forking and adding HTML support myself now that I've learned how typst works internally. It would require making non-fixed-position version of the typeset function, and possibly modifying compile to be a generic to output using either the fixed-position PDF-style builder or the freeform HTML-style builder. It looks like it would be easiest to have the free-form typeset directly emit HTML instead of the 2-step method PDF uses.

Im wondering, since I've never contributed to a large project like this, how much I can modify the library? Typst seems to make almost everything public so Im hesitant to rename or modify builtin function signatures so some feedback on what's acceptable would be appreciated.

[laurmaedje]

I wouldn't care too much about breaking changes and HTML export should indeed be 1-step instead of 2-step. However, we have planned to split up the current layout phase into two, where the first results in a fully styled, semantic document model. This would then serve as the source for HTML export and layouting.

[drewcassidy]

Understood. I'll hold off in my efforts for now.

#page -> Doesn't make sense in context of web media

I disagree. For example if using for a static site builder it might be useful to paginate things, like with a list of articles.

[janosh]

Afaik KaTeX uses MathML under the hood where possible but is more fully featured and might be less hassle than MathML itself.

[Enivex]

Afaik KaTeX uses MathML under the hood where possible but is more fully featured and might be less hassle than MathML itself.

That would require converting typst math to LaTeX math instead, and KaTeX supports an even smaller subset of that than MathJax.

MathML Core is the way to go.

[janosh]

I see. Out of curiosity, how big of an undertaking is HTML export? Doable in weeks/few months/many months?

[BirnadinErick]

what if we convert the typst to markdown, then let markdown ecosystem take care of the rest? am I not thinking correct?

[Enivex]

what if we convert the typst to markdown, then let markdown ecosystem take care of the rest? am I not thinking correct?

That conversion would be very lossy.

[laurmaedje]

I see. Out of curiosity, how big of an undertaking is HTML export? Doable in weeks/few months/many months?

We first need to rework some internals. I'd say a few months.

[nathaniel-brough]

This would be more an architectural thought (that I'm naiively suggesting without fully understanding typst internals), but I wonder if it would make sense to create an intermediate representation. Something akin to LLVM-IR but for documents. For example rustc (clang and many other compilers) will first compile to llvm-ir and then use llvm tooling to convert the IR to some sort of machine code.

This sort of a pipeline would look something like;

• typst AST -> Document-IR (intermediate representation)
• Document-IR -> PDF... OR
• Document-IR -> html... OR
• Document-IR -> insert your format here.

This would be nice for a couple of reasons.

1. Someone could create an entirely new front end for Document-IR similar to how clang and rust are front ends for LLVM-IR.
2. You could decouple the final format from the intermediate representation so adding a new format (e.g. EPUB) would become significantly easier.
3. Any exporters for the document-IR format could be shared between front ends.

[timjs]

I've extended the Pandoc reader and writer to support class attributes on blocks. This is an experiment.

Now

<div class="warning">
  <p>This is a warning</p>
</div>

is equivalent to

#block(class: "warning")[This is a warning]

in both directions (Typst ⇒ Html and Html ⇒ Typst). This also works for other formats than Html.

This is not officially supported by Typst currently. It will give you an error on "an unexpected attribute: class".

Try it out, let me know if it's useful. The code is here.

[bluebear94]

I think we’ll eventually want to have support for class attributes (chiefly for HTML, though it’ll probably be useful for general styling as well), but I don’t like the idea of using strings, which is prone to name clashes between different packages. Instead, styling classes could be their own type, though unfortunately, this doesn’t change the fact that CSS class names aren’t namespaced. If nothing else, Typst could warn about name clashes between different class objects, and the user could remap the offending classes using something akin to a show rule.

We would also need a way to specify the id attribute, but that can be done through labels.

[tsukinoko-kun]

but I don’t like the idea of using strings, which is prone to name clashes between different packages

The concern is generally valid.
When using a specific prefix, the chance for a clash becomes negligible. Something like typst__ like it's used in the BEM (Block-Element-Modifier) naming convention used in professional CSS before Tailwind was a thing.

[bluebear94]

but I don’t like the idea of using strings, which is prone to name clashes between different packages

The concern is generally valid. When using a specific prefix, the chance for a clash becomes negligible. Something like typst__ like it's used in the BEM (Block-Element-Modifier) naming convention used in professional CSS before Tailwind was a thing.

That wouldn’t solve the problem of clashes between packages, unless you mean having the prefix be unique for each package.

Of course, you could leave the problem of avoiding name clashes to the packages themselves, in a similar way as C libraries do in the absence of namespaces, but that requires conscious effort.

[nathaniel-brough]

This is somewhat of a solved problem in c++ and rust with name mangling. e.g. https://rust-lang.github.io/rfcs/2603-rust-symbol-name-mangling-v0.html

[samimaat]

Localization

I want to add to this that when following MathML Core, the development of HTML export should take into account (at least) the different usage of thousand and decimal separators when it comes to other languages.

Context

This might prove a challenge, since depending on the context in MathML (Core) a comma can be a decimal separator in a number <mn> or an operator <mo>. For example:

• Markup for 3,14 would be <mn>3,14</mn>
• Markup for a 2D point (1,5) would be <mo>(</mo><mn>1</mn><mo>,</<mo><mn>5</mn><mo>)</mo>

This is not apparent in the MathML Core specification, but is shown in the examples in MathML 3 (3.2.5.4 Examples with fences and separators) and MathML 4 (3.2.5.4 Examples with fences and separators). I understand that MathML 3 isn't well supported, but it is the recommendation. Seeing that MathML 4 is being worked on it would be a good idea for future-proofing that these things would be taken into account when handling the HTML export.

This might prove difficult to implement when wanting to maintain Typst's simple typing experience, since this case (and many others) are context-based.

Invisible operators

It should also be taken into account that there are invisible operators (MathML 4) such as the invisible times and function application, which are used to make the expression $a(x+1)$ unambigious: "a times in parentheses x plus one" or "a of x plus one".

There should be a way to give these as input in Typst. It is an issue of correct markup and accessibility.

Separate issue?

I don't know if these MathML specific things should be actually brought up as its own issue, since there is a lot more to go into and it might derail what is mainly about the HTML output. I do think that the MathML is essential for HTML output as well, which was reflected well in the first comment. Much appreciated!

[arHSM]

#page -> Doesn't make sense in context of web media
#pagebreak -> Same as #page

Ignoring this doesn't make sense, pages on the web can be printed, for use cases like blogs, documentation/reference manuals, web novels/books, etc. printing is a natural consideration.
As such supporting #page and #pagebreak makes a lot of sense!
Print stylsheets are already an existing and standardized concept, there's a @page css at-rule that #page can be translated to, and #pagebreak can be translated to an empty container with break-after: always;

Edit: My bad, just saw similar arguments have been made in the past

P.S.
Tangent but imho for #raw instead of highlight.js (that does higlighting after page load at runtime) it would be much better to just embed the highlighted output directly, fwiw syntect (the crate typst uses at the time of writing) supports html export

[tbodt]

FWIW there is a work in progress posted at d7107be

[4e554c4c]

A quick note about MathML, since I'm pretty involved in some initiatives for creating interoperable mathML (specifically on the fediverse, like on mastodon)

If typst generates MathML, it should leave an <annotation/> node on the top level containing the original source (which would allow for "un-rendering" the generated equation).

This annotation node needs an encoding attribute, hopefully containing the mime-type. I don't think typst has a mime-type yet, but to match TeX this should be application/x-typst.

[laurmaedje]

Work on HTML export is properly starting now. We've opened a tracking issue where you can follow the progress: #5512

[MDLC01]

Regarding invisible operators (previously mentioned in this thread by @samimaat), they are the topic of section 22.6 of the Unicode 16.0.0 Core Specification, as well as section 2.14 of UTR #25.

Ideally, Typst should probably output them by default. Sadly, this is probably impossible to do right. If we want to allow users to emit those characters easily, they should be added as symbols to Codex, which is the topic of typst/codex#45.

[vsheg]

A minor suggestion: Typst comments should be exported to HTML comments. This would simplify altering generated files from the very beginning, e.g. include custom HTML code:

// include interactive_plot.html → <!-- include interactive_plot.html --> → replace the comment with code

[FeldrinH]

A minor suggestion: Typst comments should be exported to HTML comments. This would simplify altering generated files from the very beginning, e.g. include custom HTML code:

// include interactive_plot.html → <!-- include interactive_plot.html --> → replace the comment with code

Should they? I generally use comments for things I don't want to include in the final published text (e.g. answers to exercises, which I don't want the students to see). I don't really want them to appear in the HTML output, even if you have to use inspect element to read them.

[vsheg]

@FeldrinH Generated HTML would require post-processing in most cases (at least for inclusion/publishing) until Typst becomes a full-fledged website builder (I hope it won't). Moreover, HTML is not a human-readable format; it's a markup language. Non-obfuscated output might be beneficial in many cases. I would definitely prefer to have high-quality HTML, rather than a publishing-ready (e.g., minified) version. Having some options to control this would be helpful, of course.

[bastienvoirin]

@FeldrinH Generated HTML would require post-processing in most cases (at least for inclusion/publishing) until Typst becomes a full-fledged website builder (I hope it won't). Moreover, HTML is not a human-readable format; it's a markup language. Non-obfuscated output might be beneficial in many cases. I would definitely prefer to have high-quality HTML, rather than a publishing-ready (e.g., minified) version. Having some options to control this would be helpful, of course.

For those use cases, because source comments are not expected in a built artefact like Typst's HTML output, I think that the inclusion of comments should be opt-in, and perhaps make use of html.elem or other explicit constructs. Also, a beneficial side-effect of such constructs would be to make directives like your include less brittle than a comment.

[MDLC01]

There should probably be a ways to emit comments (such as with a html.comment element). But I disagree that Typst source comments should turn into HTML comments. I expect the comments I write in my source code to have no effect on the output. In particular, they should be able to contain sensitive information without fear of a leak.

[CaveNightingale]

A minor suggestion: Typst comments should be exported to HTML comments. This would simplify altering generated files from the very beginning, e.g. include custom HTML code:

// include interactive_plot.html → <!-- include interactive_plot.html --> → replace the comment with code

My point is that, considering the consistency, if pdf outputs do not contain comments, then so do html outputs.

[leonardopedro]

One suggestion/request: I think typst to semantic HTML conversion is a bit of a waste of time (probably a lot of time), because if typst would be "compatible" with semantic HTML, typst itself wouldn't be necessary in the first place. The reason I am using typst is because it is the only way I can write scientific content which can be efficiently converted to svg using a small wasm plugin.
typst to faithful HTML also makes little sense, since typst can be converted to PDF and there are now AI tools which can process PDF files and convert them to faithful HTML.
Typst is post-HTML. So, it should be integrated into post-HTML tools, such as slint.dev or makepad.nl . For instance, slint is also semantic (a kind of mini-HTML much more efficient to run), it is being developed in Berlin (so the main developers can even meet personally), it can be run inside every browser and in virtually any low-memory device (no browser needed), there is a powerful extension in VScode for slint. Moreover, slint has an interesting future-proof business model around IOT devices, which could benefit Typst.
Starting from this work https://github.com/Myriad-Dreamin/typst.ts , integrating typst with slint or makepad.dev should be straightforward, it would just involve merging two plugins (at least in the browser, outside the browser it would require a tighter integration with slint which may be a bit more work it may need tinyvg.tech , I do not know).
For most usecases, as long as it runs in the browser and it is light, it doesn't have to be HTML.

Moreover, some typst extensions overlap with what slint does better, and it will become worse overtime. Integrating typst with slint, would allow many relevant extensions of typst.

[laurmaedje]

I'm not sure I see the connection to slint and makepad. These are UI toolkits rather than document processors. It sounds like you want to use Typst-as-WASM in a MathJax-like way, to embed equations into UI? That's a valid use case and fairly easy to do as a community plugin. But the idea behind the HTML work is a very different one. It's about creating complete, semantic websites that can be viewed without a Typst WASM runtime.

[leonardopedro]

I'm not sure I see the connection to slint and makepad. These are UI toolkits rather than document processors. It sounds like you want to use Typst-as-WASM in a MathJax-like way, to embed equations into UI? That's a valid use case and fairly easy to do as a community plugin. But the idea behind the HTML work is a very different one. It's about creating complete, semantic websites that can be viewed without a Typst WASM runtime.

You are stating the connection in your own reply: "It's about creating complete, semantic websites that can be viewed without a Typst WASM runtime" this is precisely what slint does well (apparently, at least, I am not a slint expert). Note that slint runs in a low-memory device, so it has particular design choices, different from javascript-like websites, but this is a matter of taste.

A code example: slintpad.com

About the ePub usecase, since slint runs in low memory devices it can in theory run in all devices that run ePub and much more. Of course, in the short term some devices may run ePub and not slint, but most of these devices can be software updated, so I guess it would be a short term issue.

About the static site generator (example https://www.npmjs.com/package/hexo-renderer-typst ): wasm (and so slint) is compatible with static site generator. It is not single file, but the complexity overall I think is lower with slint (this is a bit of a matter of taste, many people may disagree, but it is what I think). The main problem with HTML is that if it would be possible, then typst would probably not have been created and MATHML would be a success: in fact, the complexity is large.

[dodgepong]

The primary use case I see for Typst to HTML is to generate ePub documents, which still see a lot of use and are often more accessible than PDFs.

[pmazaitis]

Another use case: adding Typst to HTML output to static site generator inputs in order to support single sourcing. For this, pure semantic HTML is all we need (and all we really want).