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.)