Now accessible – Typst Blog

Typst 0.14 is out now. With accessibility by default, PDFs as images, character-level justification, and more, it has everything you need to move from draft to production.

by Laurenz Mädje
and Martin Haug

Typst’s origins lie in academia, but over the past year, we’ve seen it expand to so much more. It’s increasingly being used in the industry: For manually written documents, partially automated reports, and in fully automated batch PDF generation pipelines. Across these use cases, it’s being used in production for critical documents.

In August, we launched a new website to reflect Typst’s expanding scope, and now, with Typst 0.14, we’re shipping crucial features that make Typst even more widely applicable.

If you need to comply with accessibility-related regulations, Typst 0.14 has your back. Typst now generates accessible documents by default, with opt-in support for stricter checks. For those working with complex illustrations, PDFs are now supported as a native image format. In case you’re typesetting a book, the new character-level justification will give your layout the final touch. And if you’re building a website or blog, many improvements to Typst’s HTML export are waiting for you.

Contents

In this blog post, we’ll take a closer look at the highlights of this release:

To get started with Typst 0.14…

• …in the web app: Just open any of your projects! You’ll get a prompt offering you to upgrade to the latest version.
• …in the command line: Run typst upgrade in your terminal or, if you haven’t installed Typst previously, download the latest version of the CLI.

For a comprehensive overview of all changes in the release, visit the changelog. If you’re looking to upgrade your document to Typst 0.14, you can also skip ahead to the Migration section.

Accessibility

Not everyone reads PDF documents the same. Some people read on large screens or print; others use small phones or screen readers to have documents read aloud. To cater to all these uses, a file must contain tags that allow Assistive Technology (AT) like screen readers to learn about the reading order and semantic meaning of each piece of text. Tags allow AT users to learn which text is *strongly emphasized*, enable navigation of the document by skipping between headings, and more.

Tagging requires no additional work from you: If you are using the built-in markup and elements, Typst will automatically select the right tags! Unlike many other tools, PDF files created with Typst 0.14 are tagged by default, raising the bar for accessibility.

But tags are not enough to make a file accessible: To reach everyone, you need to design for universal accessibility from the start. The new features in Typst 0.14 can help you with that. Consider diagrams created with shapes or packages like cetz—their visual meaning is invisible to assistive technology. The new alt parameter on figures solves this:

#figure(
  stack(
    dir: ltr,
    spacing: 0.5em,
    rect[Tagged PDF],
    text(2em, sym.arrow.long),
    rect[Accessibility],
  ),
  alt: "Diagram with two rectangles. The first is labelled 'Tagged PDF'. An arrow points to the second, labelled 'Accessibility'",
  caption: [
    Tags enable PDF accessibility
  ],
)

With this change, AT users hear the alternative description and can grasp the figure’s purpose just like sighted users—no information is lost. We have put together a new Accessibility Guide that contains more tips on how to create accessible documents, including how to write good alternative descriptions, when to use the figure’s vs. the image’s alt parameter, and more.

To make sure you got everything right, you can enable the new PDF/UA-1 export. PDF/UA is an international standard that helps to create universally accessible PDF files. When it is enabled, Typst will run additional checks against your document to find accessibility issues and optimize for accessibility rather than compatibility. It will find issues such as missing document titles, wrong heading hierarchies, and missing alternative descriptions.

PDF standards

Alongside PDF/UA-1 support, we’ve also generally expanded Typst’s support for PDF standards. Instead of just PDF 1.7, you can now choose between the PDF versions 1.4, 1.5, 1.6, 1.7, and 2.0. And for PDF/A, we’ve expanded support from just two specific substandards to all four parts with all their conformance levels. While Typst’s defaults are perfectly fine for most use cases, choosing a standard can optimize your document specifically for your use case. Consult the expanded PDF documentation in the reference for guidance on which standards you should pick under which circumstances.

PDFs as images

Staying with the PDF theme, there are exciting news for authors that have a lot of complex illustrations. Typst now supports PDF as a native image format. What I personally find most exciting about it, is that PDF images are supported across all export targets, and for each export target in the most suitable format. In PDF export, PDFs are naturally directly embedded. Meanwhile, in HTML and SVG export, PDFs are converted to an embedded SVG on-the-fly. And, finally, in PNG export and the web app preview, PDFs are rasterized. All of this PDF processing functionality lives right in the Typst compiler, with no system dependencies. This is only possible thanks to the amazing work of community member @LaurenzV, who created a new PDF processing library called hayro from scratch. The library is 100% written in the programming language Rust (which is also the language we use for the Typst compiler) and is thus highly portable.

#figure(
  image(
    "throwing-success.pdf",
    alt: "A diagram titled 'Throwing Success' that .."
  ),
  caption: [
    Effect of normalized thrust
    on X and Y position of
    thrown emojis
  ],
)

Character-level justification

Producing a visually balanced paragraph was once a fine art, when professional typesetters still carefully set paragraphs with movable type. Nowadays, you could hope that optimal paragraph typesetting is a solved problem across all our software. But, alas, it is not!

There are different strategies we can employ to produce a well-justified paragraph. Of course, to justify the paragraph, we need to stretch each line to the width of the measure. There are different ways to do this: Most obviously, we can adjust the spacing between words. This is what most software does. But we can also adjust the spacing between characters. This is now implemented in Typst.

Other methods to do this (which we want to explore in the future) include stretching the width of characters (this is best done with variable fonts) or, for some scripts, inserting special textual elements. For example, in Arabic, there are Kashida, which allow spacing out glyphs in words by extending the connectors between individual glyphs.

But that’s just part of the recipe. Arguably, the even more crucial part is how this interplays with which linebreaks we chose to insert. Naively, we can choose our break points based on how much text fits and then perform the stretching. But we can do much better by taking into account each line’s potential for stretching with the various mechanisms discussed above! We can then choose the break points that minimize the amount of bad-looking stretching.

I was initially skeptical about supporting character-level justification because I’ve seen it done poorly in some books. But that’s actually not the fault of character-level justification per se; it’s just excessive use of it. Tastefully chosen maxima—together with an algorithm that minimizes displeasing typography—make it bring out the best in justification.

We hear a lot about microtypography when people compare Typst with LaTeX. And even though Typst uses the same fundamental algorithm as LaTeX does to optimize paragraphs, it’s true that LaTeX has some extra tricks up its sleeve. Now we do too though, as character-level justification is a feature that LaTeX does not support.

Richer HTML Export

In Typst 0.13, we shipped a first, highly experimental version of HTML export. This very minimal version already introduced the primitives for flexible HTML generation. With these primitives, the mapping of Typst elements to HTML can be expressed through show rules, just like the mapping to visual elements is performed in paged export.

What was lacking though were show rules for many built-in elements, including elements like footnotes, outlines, and citations. Typst 0.14 makes good progress in this regard. Most semantic elements (those from the Model category) are now properly mapped to semantic HTML. We’ve also improved handling of textual content in HTML export. The more visualization- and styling-focused parts of Typst’s standard library remain largely unsupported, but we plan to add support for those (to the extent possible) in the future.

Below, you can see an example of a small, but non-trivial Typst document exported to HTML with Typst 0.14.

#set heading(numbering: "1.")

= Introduction 
In @intro, let's cite @netwok.

#bibliography("works.bib")

<h2 id="intro">1. Introductionh2>
<p>
  In <a href="#intro">Section 1a>, let’s cite
  <a id="loc-1" href="#loc-2" role="doc-biblioref">[1]a>.
p>
<section role="doc-bibliography">
  <h2>Bibliographyh2>
  <ul style="list-style-type: none">
    <li id="loc-2">
      <span class="prefix"><a href="#loc-1" role="doc-backlink">[1]a>span>
      R. Astley and L. Morris, “At-scale impact of the Net Wok: A culinarically
      holistic investigation of distributed dumplings,”
      <em>Armenian Journal of Proceedingsem>, vol. 61, pp. 192–219, 2020.
    li>
  ul>
section>

Another exciting addition to HTML export is the new typed HTML interface. Typst’s html module now includes functions for constructing HTML elements with strongly-typed attributes. This means you can now write

#html.video(
  autoplay: true,
  width: 1280,
  height: 720,
  src: "sunrise.mp4",
)

instead of

#html.elem("video", attrs: (
  autoplay: "",
  width: "1280",
  height: "720",
  src: "sunrise.mp4",
))

As you can see, attributes are mapped to idiomatic Typst-native types.

Last but not least, we’re happy to announce that HTML export will soon come to the Typst web app. We’re still polishing up the implementation, but plan to ship it in the coming weeks.

Migrating to Typst 0.14

As far as breaking changes and deprecations go, this is a pretty calm release. Most documents should continue to work as before. There are a few minor breaking changes that make certain validations more strict. For instance, labels, link URLs, and font lists may not be empty anymore. To learn about all breaking changes, consult the changelog and search for “breaking change”.

The release also contains a few deprecations. In particular, you’ll need to replace any use of pdf.embed with pdf.attach. Moreover, two bibliography styles were renamed and the --make-deps CLI flag was deprecated in favor of the new, more flexible --deps flag with --deps-format make. There are also a few deprecated symbols. The compiler will warn you about all use of deprecated functionality.

In the web app

With this release, we’re also bringing a better version upgrade experience to the web app. Previously, projects would always use the latest compiler version unless explicitly pinned to a specific version in the settings side panel.

We are now phasing out the “Latest” option. Instead, the web app detects when a new version is available since you’ve last edited a project, and offers you to upgrade. The upgrade assistant includes an automatic compatibility check that compiles your document with both versions, makes a verdict, and lists new errors and warnings.

Typst 0.14 is the result of 8 months of hard work by us and the community. We hope you are as excited about it as we are!

Speaking of the community—We’re hosting a community call on Discord on Friday, November 7th. Join us to share your experiences with the new version and to chat with the community!