So far, the landscape for batch PDF generation has been dominated by these tools, each with its distinct strengths and drawbacks:

• LaTeX: LaTeX offers beautiful typography but was designed for manually edited manuscripts, not automated generation. Ingesting data requires either generating LaTeX source code with custom, error-prone scripts, or writing Lua scripts executed by the LuaTeX compiler, both of which have a steep learning curve. LaTeX distributions are large (> 1GB), making them ill-suited for deployment in serverless environments, and compilation is slow – often taking multiple seconds per document. LaTeX also needs careful configuration to emit accessible PDFs. It is easy to run into EAA or ADA liabilities when missing this.

• Browser-based solutions: HTML and CSS skills are widespread, making this approach attractive from a talent perspective. However, the workflow requires two steps: converting data to HTML with careful escaping, then rendering to PDF. Tools like Headless Chrome and the now-unmaintained wkhtmltopdf use full browser engines but lack paged document capabilities. Specialized tools like WeasyPrint and PrinceXML extend CSS with more paged layout features but lack modern CSS and JavaScript support (PrinceXML only supports ES5 from 2009; WeasyPrint does not support JavaScript). You will also need to maintain custom, tool-specific scripts to feed your pipeline.

• Apache FOP: An XML-centric workflow where data must be formatted as XML (DITA, DocBook, or custom) and combined with XSL-FO stylesheets for layout. While mature, XSL-FO is complex to learn, and the standard was abandoned in 2013. Many users now switch to browser-based workflows, transforming XML to XHTML with XSLT and then applying CSS for styling – requiring two steps instead of one.

In addition, there are more specialized tools for businesses immersed in a specific ecosystem like Power BI Report Server and SAP Crystal Reports. These solutions have great integrations with their ecosystem, but are costly to phase in and focus on data and do not offer strong formatting capabilities.

Instead, let's take a look at Typst. Its properties make it ideal for batch document generation, with capabilities that scale from individual documents to millions of PDFs per day:

• Compilations in Typst commonly complete in milliseconds, making it cost-effective to run with large workloads.
• Typst allows you to load data from any format, with parsers for XML, JSON, and CSV included. With a package, you can also use Markdown.
• Documents compiled with Typst are accessible out of the box. You can choose to target PDF/UA-1 to ensure compliance with accessibility standards.
• Typst is designed for paged media and includes rich styling and layout tools.
• Typst integrates its own scripting language, allowing you to load, analyze, transform, and format your data, all in one system.
• Typst is a single lightweight (~40MB) and secure binary that is easy to deploy and run in containerized cloud environments.
• Typst is actively maintained by our team at Typst GmbH and a community of over 300 open-source volunteers.
• Typst can be integrated as a CLI tool or Rust library, giving you flexibility for your deployment.

Below, you will learn how you can use Typst for your own batch generation pipeline. This article should give you a head start and show you all the tricks you need to know to effectively generate PDFs with Typst.

In order to set up a Typst project for automated document generation, you will go through these steps:

1. Define a template for your data
2. Load your data with sys.inputs
3. Parse your data
4. Insert your data into the template and compile the file

First, let's start by defining a template. When using Typst for manually edited documents, you use markup to insert all of your content. Let's have a look at some basic markup:

Hello *Peter,*

You have accrued
#underline[100 GlorboCorp
Rewards Points] last year!

In this file, we typed all of our content manually. We used asterisks to render the customer's first name bold and underlined their loyalty account balance. The objective is clear: the point balance and the customer's name should be automatically inserted.

To do this, let's first learn about variables: Because Typst integrates a programming language, Typst documents can define and use variables. Here is a quick look:

#let first-name = [Peter]
#let points-balance = 100

Hello *#first-name,*

You have accrued
#underline[#points-balance
GlorboCorp Rewards Points]
last year!

We have used let to define a name and value for our variable. Then, we have inserted the value in markup using the hash. You can learn more about variable definitions in our tutorial and the reference.

Of course, the name and points balance is still static between compilations. This is where, for other tools, you would write your own script to populate these fields using your data. In Typst, this approach is strongly discouraged: Our markup is not designed to be generated by machines. Instead, skip external scripting and just do it in Typst itself.

Normally, when you compile your document using the open-source Typst compiler, your CLI call may look something like this:

typst compile main.typ

In this call, Typst will compile the file main.typ to a PDF. To customize the document, we can add the --input flag to pass custom data:

typst compile --input first-name=Peter --input points-balance=100 main.typ

Now, we can change our Typst file to use the inputs we passed on the shell:

#let (first-name, points-balance) = sys.inputs

Hello *#first-name,*

You have accrued
#underline[#points-balance
GlorboCorp Rewards Points]
last year!

Try to call this with different inputs and you will see that we successfully set up our first automated document in Typst! The principles for all batch generation in Typst are the same: Use the --input flag to pass inputs and then use them in your template using sys.inputs. Note that CLI inputs are provided as strings. If you need numeric values, convert or parse them (int, float, JSON parsing, etc.).

Now, we can use Typst's styling capabilities to build out our template:

#import "@preview/zero:0.5.0": num

#let (
  first-name,
  points-balance,
) = sys.inputs

#let num = num.with(
  math: false,
  group: (
    separator: ",",
    size: 3,
    threshold: 0,
  ),
)

#set page(header: align(
  right + bottom,
  image("logo.svg"),
))
#set text(font: "IBM Plex Sans")

Hello *#first-name,*

You have accrued
#underline[#num(points-balance)
GlorboCorp Rewards Points]
last year!

In this example, we have used two set rules to insert the company logo in the header and to set the brand font. The logo image should be in the same directory as your Typst file. All fonts on the system will be automatically discovered by Typst. You can add an additional directory for fonts with the --font-path flag.

We also imported the package zero from Typst Universe. It provides powerful capabilities for number formatting. Here, we are using it to introduce a decimal separator in the point balance. You can use all of the packages and templates on Typst Universe to create your document. Many of them can give you a head start, so take a look!

Another tweak we made is to use destructuring to assign the keys from the sys.inputs dictionary to our two variables. Destructuring can help to write more concise templates.

Finally, let's explore how you can load and transform data in structured formats with Typst. So far, we have only seen single, self-contained pieces of data being passed in individual inputs. Let's instead have a look at how to load data from a single JSON file:

To start out, here's the JSON file from which we will create the document. In production, you may have retrieved this data from your API or your database.

{
  "firstName": "Mike",
  "totalSpend": 12048.1
}

The JSON file contains a single object with two keys, firstName and totalSpend. The firstName key will just be pasted in our document like the first-name input before. However, we do not have the points balance anymore, instead, we got the total spend of the customer in USD as a number.

Suppose we can calculate the point balance from the customer’s total spend using the formula $8 spent = 1 point, rounding down. With other systems, it would now be more convenient to pre-process your data in a custom script. However, in Typst, we can do it right in the template:

#import "@preview/zero:0.5.0": num

#let customer = json(bytes(sys.inputs.customer))
#let first-name = customer.firstName
#let total-spend = customer.totalSpend

#let points-balance = calc.floor(total-spend / 8)

#let num = num.with(
  math: false,
  group: (
    separator: ",",
    size: 3,
    threshold: 0,
  ),
)

#set page(header: align(
  right + bottom,
  image("logo.svg"),
))
#set text(font: "IBM Plex Sans")

Hello *#first-name,*

You have accrued
#underline[#num(points-balance)
GlorboCorp Rewards Points]
last year!

Compared to the examples before, this document does not expect multiple inputs, but just one, customer. It is expected to contain a JSON object. We use the JSON function to parse it and can then access its keys. Below, we calculate the number of points using a division and calc.floor. In this example, we have seen that we can load input data from formats like JSON and apply complex transformations with Typst's integrated scripting language.

Let's try this with this JSON file called mike.json. We will call Typst with the contents of the file provided by a subshell:

typst compile --input customer="$(cat mike.json)" main.typ

Now we got our document with Mike's data, including the point balance computed from his revenue.

With these fundamentals in place, you're ready to build production-scale PDF generation pipelines with Typst. You can process thousands of documents by iterating through your data files, calling the Typst CLI for each record, and leverage parallel processing for maximum throughput.

For production deployments, consider:

• Using Typst as a Rust library to shave off the startup overhead from launching the CLI and discovering fonts for each job. The time saved per compilation ranges between 5 milliseconds (minimal fonts) and 100 milliseconds (desktop system with many fonts).
• Deploying with our official Docker container for consistent, production-ready environments
• Implementing caching strategies for templates and assets to minimize overhead
• Disabling the use of system fonts for better reproducability and startup speed using the --ignore-system-fonts flag and instead specifying just the required fonts using --font-path
• Choosing an appropriate PDF standard like PDF/A or PDF/UA
• Monitoring compilation times and PDF sizes to catch issues early
• Setting up automated testing with sample data to catch template regressions

Ready to get started? Download the Typst open-source compiler or explore the full documentation. If you need enterprise support, contact us. We work with organizations from startups to Fortune 500 companies and can help you build a fast, maintainable PDF generation pipeline that meets your specific requirements.

The chasm between accessibility and reality

It's true that accessibility is an important quality of every document: Without it, you are excluding a lot of people from your document, losing you exposure and creating friction. Depending on your organization's and country's policies, accessibility might even be required. Yet, with most software, accessibility remains an afterthought – a checklist to complete manually after the document is otherwise finished.

Instead, what if accessibility was taken care of by the time you are done with your project? If you did not need to manually follow a checklist, but had accessibility issues raised to you throughout the writing process? What if you could be certain that the resulting file will offer screen reader users a good experience and matches international accessibility standards?

Fortunately, that's exactly what we have built with Typst. Typst is a markup-based professional writing platform. When using Typst, you write your content and add structure with markup. Typst will use this markup to format your document with a template and publisher-grade typesetting, and crucially, it also uses the same information to create an accessible file. This means that if you follow just a few best practices, your file will be accessible when it looks right.

Basics: What makes a PDF accessible?

But let's take a step back: What does it mean for a PDF to be accessible? To the layperson, there are a few visual and a lot of hidden distinctions. First, an accessible PDF is designed to accommodate readers who have difficulty distinguishing colors or reading low-contrast text. You can achieve this by choosing high-contrast foregrounds and backgrounds and ensuring no information is conveyed solely through the use of color.

But the normally invisible features are what sets a high-quality PDF apart: At a technical level, it contains semantic data screen readers use to read the file correctly to users with low or no vision. Without this data, your file may have any or all of the following problems when read by a screen reader:

• It will be read in the wrong order
• The contents of images and graphics will not be announced
• The screen reader may fail to use your document's language to determine the right pronunciation,
• The text within your document might not be read accurately

Additionally, an accessible file allows screen reader users to navigate between sections and understand when content is emphasized. The data that prevents these issues and enables seamless navigatation of your file is called tags.

How to get a tagged PDF

Tagging PDFs is where you run into problems with most software. When manual formatting is encouraged over an automatic template, software simply cannot write the right tags. Is your bold text with larger font size a heading? A pull quote? Or just strong emphasis? Tags make this distinction explicit by telling the screen reader what each part of the document means on a semantic level. However, even when using tools like Word’s built-in formatting presets for headings etc., not all content that should receive dedicated tags actually gets them, creating the need to manually post-process the file in Acrobat. The boldface button's decade-long allure to Word users is unbroken – and it's standing between authors and accessible documents. Finally, many tools require special settings to produce a Tagged PDF. For example, printing to PDF will result in an untagged file. Even in LaTeX, the user must use the relatively new and little-known macro \DocumentMetadata to receive a tagged file.

Typst takes a different approach. We structured Typst around elements, building blocks that carry meaning, not just appearance. If you have already used Typst, you have interacted with them, even if you did not realize it. For example, every character in your document is part of a text element. Likewise, every time you used asterisks for boldface, you create a strong emphasis element. This extends to tables, bibliographies, and more.

Many of Typst's elements have strong semantic meaning vital to screen reader users. We mentioned headings above. The figure and the table elements are equally important: Screen readers can only help users understand complex content like tables and images if they are properly tagged. Typst uses the rich semantic information it already has about these elements to automatically write tags in the final PDF.

Accessibility out of the box with Typst

In this section, we will take a closer look at Typst's design makes it easy to create accessible files. As mentioned above, elements are central to Typst and pervasive across all documents. Therefore, the easiest way to create your document is also the most accessible. Consider the following example, for a brochure where emphasis is rendered in blue. First, let's look at an example that uses the strong emphasis element with markup and a show set rule:

#show strong: set text(fill: blue)

Join us for a David Lynch double
feature with *Mulholland Drive* and
*Inland Empire* next Tuesday
at 8:15 PM.

Next, let's look at what happens when we manually apply the formatting with the text function instead of using semantic markup:

Join us for a David Lynch double
feature with
#text(fill: blue, weight: "bold")[
  Mulholland Drive
]
and
#text(fill: blue, weight: "bold")[
  Inland Empire
] next Tuesday at 8:15 PM.

This example looks identical to the first one, but it has fatal flaws. First, we need to repeat the formatting parameters each time, making changes tedious and error-prone. More importantly, the emphasis has become invisible to screen readers. The formatting instructions had no effect on the semantic information exposed to assistive technologies. Typst's design actively encourages use of its built-in elements: Set and show rules only work with elements. They are exposed with convenient markup and enable you to use the powerful templates on Typst Universe. By following our best practices, accessibility comes automatically.

There are some elements that play an outsized role in accessibility. When editing your document, always remember to use these elements when applicable:

• Use table.header and table.footer for header and footer rows instead of normal cells.

• Use table if tabular layout conveys data, and grid when used exclusively for design purposes.

• Use the list, enum, or terms elements for lists.

• Use the figure element to enclose and describe graphics.

For some elements, Typst needs more information than it can infer from markup alone. Instead, your input is needed. The most prominent example for this are images and graphics. Since screen reader users cannot see them, you need to provide an alternative description that the screen reader can announce instead. Use the alt parameter of the image function:

#image(
  "heron.jpg",
  // The verbosity required for the
  // alternative description depends
  // on the context of the image.
  alt: "Heron in flight with feet and wings spread",
)

Typst also allows you to draw figures, either with the built in shapes and paths or with packages like CeTZ. To provide alternative descriptions for these, use the figure element's alt parameter. We have compiled guidance on how to write good alternative descriptions in our Accessibility Guide.

More checks for maximum accessibility & compliance

Because it's easy to forget alternative descriptions, Typst can surface errors when they're missing. When you opt into PDF/UA-1 export, Typst will check for accessibility issues during export. If it finds critical issues like missing alternative descriptions, it will not create a PDF and instead show you what to change. PDF/UA-1 is an international standard for universally accessible files that provide the best possible experience for screen reader users. You can enable PDF/UA-1 in the PDF export dialog in the web app or with the --pdf-standard flag on the CLI.

No matter whether you choose to enable PDF/UA-1 or not, Typst writes Tagged PDF files by default, providing a baseline for accessibility. For other topics around accessible files, like use of color, natural language specification, and more, be sure to check out our Accessibility Guide.

Conclusion

Throughout this blog post, we have seen what creating accessible PDFs has meant so far and how it can look with Typst: Instead of following checklists, running external validators, and manually fixing tags in Acrobat, Typst leverages semantic elements and built-in validation to create PDFs that are accessible from the moment they compile. With this approach, accessibility is no longer a compliance chore imposed by the EAA, ADA, Section 508, or other regulations. Instead, it becomes an asset: well-structured, maintainable documents with scalable templates that reach your audience, regardless of how they access your content.

Try Typst in our web app or with the open-source compiler and benefit from accessibility by default. And to make even more informed choices, learn about the best practices about universally accessible documents in our documentation.

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:

• Accessibility
• PDF standards
• PDFs as images
• Character-level justification
• Richer HTML export
• Migrating to Typst 0.14
• Community Call

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.
• …on the command line: Run typst update 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 <intro>
In @intro, let's cite @netwok.

#bibliography("works.bib")

<!-- html, head, and body omitted for brevity -->
<h2 id="intro">1. Introduction</h2>
<p>
  In <a href="#intro">Section 1</a>, let’s cite
  <a id="loc-1" href="#loc-2" role="doc-biblioref">[1]</a>.
</p>
<section role="doc-bibliography">
  <h2>Bibliography</h2>
  <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 Proceedings</em>, 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.

Community Call

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!

First, we are adding folders for projects to Typst Pro. You can use folders in your personal workspace or a team. Create a new folder in the toolbar and then drag projects into it. You can also use the new, unified project settings modal to move your projects.

Folders have been one of the most sought-after features for the Typst web app. Taking a look at our issue tracker, the feature request for folders had 37 thumbs up, making it the second most requested feature. This tracks with our data: The top 20% of our registered users have about 12 projects on average. Using folders, you can sort your projects by topic, start date, or more. Additionally, some users have been using single-person teams to work around the missing folders. However, this quickly runs into the limitation for maximum teams per account. We would suggest that users with this setup migrate to folders. To learn more about how folders work, check out their docs page.

Another source of chaos beyond project management? Collaboration. When Typst Pro users share a project, they can get feedback as comments by their collaborators. However, so far, people needed the permission to write in your project to leave comments. Today, we are adding a new share link that allows comments, but not other changes to the project. If you are a Typst Pro subscriber, you can create the new review-only share link from the Share modal or change the permissions of existing project members.

Not a Typst Pro subscriber yet but curious to tidy up with folders and review-only shares? The first 40 people to use the code FOLDERS can get a free first month of Typst Pro. You'll also get to use comments, private packages, GitHub, GitLab, and reference manager sync, and more. Subscribe here!

We are looking forward to hearing about your experiences with these new features. Use the "Feedback" button in the "Help" menu and let us know what impact on your workflow these features and Typst have had.

The Typst compiler has gained hundreds of features, big and small. Would you believe that just two years ago, Typst did not even support footnotes? Ever since, we have raced ahead to make Typst a great choice for technical documents, both in the industry and in academia. Among many other things, you can now...

• ...meticulously customize tables to represent even the most complex datasets.
• ...use Typst's powerful scripting capabilites to auto-generate your document from data sources like JSON and XML files.
• ...reason about the content and layout of your document with context.
• ...use packages and templates from the community or build and share your own.

As a company, we have grown financially sustainable over the past two years. Our team has grown to five members across three countries. We have introduced three new offerings: Typst Pro is our subscription to get the most out of the Typst web app. With Typst On-Premises, enterprise and security-conscious organizations can self-host the web app. Finally, Typst Open Source support lets teams building on the Typst compiler access the expertise of our team. Our dream was always for our company, Typst GmbH, to serve as a backbone for progress in our open-source software, a goal we have now achieved.

Our community has exploded in size and awesomeness: At the time of writing, Typst has over 44K stars on GitHub, putting it in the same ballpark as the new and trending programming language Zig (40K stars) and Prisma, a popular tool for working with databases in JavaScript (43K stars).

We are aware that creating a community is not only about making a number go up: We have launched the Typst Forum as a place for Typst users to help each other out and show their projects to the world. In the Questions category alone, the Forum has accumulated over 1,600 threads with answers for common and not-so-common challenges new and returning users face. Not only do these threads get the questions of their original posters answered, they also help everyone else: They can easily be found through search engines by others facing the same problem, creating a great knowledge base!

For us, a big milestone was the launch of Typst Universe, where Typst users can share packages and templates. With Typst Universe, every user can benefit from the work of some of our most advanced community members. Since the inception of Typst Universe, over 400 packages and about 390 templates were published. They range from custom elements like glossaries and algorithms, over checklist and project management templates, right down to packages for drawing all kinds of diagrams.

And finally, there is the Typst Discord, which was the original gathering place of our community and still fulfills a vital role in open-source development, chatting with other Typst users, and getting quick answers. This space has grown to over 11,000 members, which is just awesome.

We would like to thank everyone who engages in our community, be it on the Typst repository on GitHub, by posting on our Forum, publishing on Typst Universe, or by chatting on the Discord! You make Typst better and we hope that it can give something back to you in return.

With all of this progress over the past two years, we felt that our old landing page did not do the best job of representing all that Typst is. Hence, we are launching a new landing page today. It highlights all the ways that Typst can help you if you are writing technical documents. The beautiful drawings that showcase the diverse set of use cases people have for Typst were created by Joey. Check out his work.

To make it even easier to get started with Typst, we have also created a new interactive playground at https://typst.app/play. There, you can experiment with the Typst language and app without signing up first. We've seen many times that just showing Typst to people and letting them play around with it is the best way to introduce them to Typst. For this reason, the new playground is linked as the most prominent destination on our new landing page.

Last but not least, we have added an entirely new, dedicated open source page that shows off the Typst compiler, explains how you can download it, and tells you more about our approach to open source in an FAQ.

If you recall our old landing page, you may have noticed that the new page represents a bit of a vibe shift. As opposed to before, academic writing is not our only focus anymore. This shift is based on real experience we had with our users. Having started Typst out of university to scratch our own itch with paper writing and assignments, Laurenz and I originally positioned it as a tool for students and researchers, knowing that Typst was good at that.

However, with a growing user base, we have seen proof that Typst solves real problems in industries like Cybersecurity, Finance, Aerospace, and Engineering. Using a document writing platform can be an enabler for professionals in more than one way. A crucial aspect of this is that teams can build domain-specific templates and automations with Typst. This scales all the way to generating complete deliverables from machine-readable files.

In this new world, Typst is deployed by industry-leading enterprises: IABG is deploying Typst On-Premises in their aerospace department while the cybersecurity company Neodyme is using Typst On-Premises to work on client reports. Typst sees usage well into the Fortune 500, for example at UBS. We are a part of the bank's journey to create transactional documents more scalably with Typst Open Source Support. And of course, Typst is used in more than 3,500 laboratories and universities worldwide. If you ever hesitated to recommend Typst before, know that Typst users are in good company.

We don't want to stop here: Our mission is still to become the best solution for technical writing. That is why we will soon release Typst 0.14 with PDF accessibility as a marquee feature: Regular PDF files are notoriously difficult to use with Assistive Technologies like screen readers. That makes them inaccessible to some disabled users and creates a compliance problem with the European Accessibility Act (EAA), the Americans with Disabilities Act (ADA), and other regulations. With Typst 0.14, your documents will become accessible by default, tagged for use with Assistive Technologies. Beyond this, you will be able to opt into explicit PDF/UA (Universal Access) export and make sure that your documents meet high accessibility standards and pass automated checkers.

Accessible PDF output will join features like show and set rules, data loading, and HTML export (in preview) to allow you to use Typst in production, no matter what your requirements might be.

With all the growth of our software, our company, and our community under our belt, our brand-new landing page, and Typst 0.14 close to completion, we are excited to take you with us on another two years and beyond of our journey to make technical writing more productive. If you are excited too, let someone know about Typst today! Regardless of whether your team is facing a document challenge or you and your friends are on the verge of getting started with your theses -- let us solve the problem of technical writing for you.

First, let's have a brief overview of our requirements. We want slides, handouts, exercises and solutions to be rendered from the same source. Having the same source helps us prevent the different documents from diverging when new content is created, as synchronizing multiple sources or tools is prone to errors. This also means we have different requirements for the shape and appearance of the documents that need to be handled. For example, the slides are mainly composed of bullet points to guide the course; in contrast, the handouts need to be more detailed and self-contained documents. Additionally, a range of people teach these courses, so we require tools that are easy to use and consistent across multiple machines. And finally, styling these documents should be flexible and provide a sharp look.

Why Typst

Our previous solution was obviously functional; however, there were limitations that we could no longer work with. That solution was Markdown and HTML-based, which works well for slides, albeit rendering handouts and exercise documents always being a struggle. Typesetting was never optimal for us: design options were limited, and the generated table of contents was often counterproductive, as it was based solely on the slide titles. So, we set out to find a new solution. Most of the tools out there are designed to either render slides or handouts, not both. Obviously, LaTeX was one of the contenders, but we decided against it due to its poor usability. In the end, we decided to use Typst!

Typst offered us a great balance between a simple-to-learn markup language and very flexible typesetting. Together with the possibility of creating custom modules, we were ready to address our requirements. In the following section, we will take a closer look at how we did that.

Our Typst Module

As described, each course contains three artefacts: slides, handouts, and solutions for the exercises. These artefacts share some of their content and parts of their structure; for example, the exercises require the same identifier in the handout and the solution. Other parts differ significantly across these documents.

What we wanted was to have a single Typst code base that can compile into different artefacts. We solved this by using the compiler's --input flag to pass the desired artefact type during compilation. This parameter is then used inside a custom Typst module, in which we bundle our logic. For example, typst compile --input mode=slide training.typ renders the slides in "presentation-16-9" aspect ratio, --input mode=handout the handout in "a4". Now, we are able to control what shows up in which artefact and how it is formatted. Additionally, for formatting the slides and handouts, we use the very good Polylux package from the public Typst Universe.

Inside our module, we categorize content via functions: a key function being the slide(title: [], slide-only: [], handout-only: [], common: [], notes: []) function. So, we still use a slide as a unit but are now able to differentiate content categories, which helps us during compilation.

#slide(
  title: "Example",
  common: [
    I am a common element.
  ],
  slide-only: [
    Just on the slides please.
  ],
  handout-only: [
    Only for the handout.
  ],
)

Since Typst is just good old plain text, we can manage all of these with Git, where every course has its own repository. Our module can then simply be included via a submodule or subtree—which which incurs a bit of overhead—yet we're happy with having each course as a self-contained unit. Finally, thanks to the statically compiled Typst executable, incorporating them into our automated pipelines was quite simple.

The Typst team's decision to use plain text is a boon that, in a world of proprietary formats and vendor lock-in, needs to be appreciated. Nonetheless, IT people still have their grievances about how plain text should be formatted, but let's not delve into that topic now. We like that everyone can use the editor of their choice to write Typst and that there's already an existing ecosystem (e.g. LSP servers).

Summary

In summary, the migration to Typst was very pleasant, and we're currently optimistic that it is a future-proof solution. We now have greater flexibility for our training course material with a justifiable increase in complexity. A big thanks to the Typst team for all the hard work, the great documentation and all the little details that result in an enjoyable product.

This is when the maintenance window will occur, depending on your time zone:

• Central European Time: 8 AM to noon
• Eastern Time: 2 AM to 6 AM
• Pacific Time: 11 PM to 3 AM
• China Standard Time: 2 PM to 6 PM

What

During that time, we will take the Typst web app down, so the following services will be unavailable:

• You will not be able to sign in to Typst
• You will be unable to view, edit, download, or export your projects
• The Typst Forum may be in read-only mode or completely unavailable

The documentation, Typst Universe, and the front page of our website will stay available, users of the local compiler CLI are unaffected, as will be users of Typst On-Premises.

Working during the maintenance window

If you need to work on your projects during the maintenance window, you can download the source files for a single project ahead of time by pressing the down-facing arrow next to the download button and choosing "Export sources as ZIP".

Alternatively, you can export all your data, including projects, from your account settings page by pressing the button in the "Download my data" section there. You can upload any changed files after the maintenance concluded.

To edit your sources locally, you will need a text editor like Visual Studio Code and the local Typst compiler CLI that you can download from GitHub. Community tools like tinymist can help to make local editing a more familiar experience while the web app is offline. If you have questions on how to set up your local environment, you can get help on the Typst Forum or on Discord.

Background

I want to share a few words about why we are performing this offline maintenance:

So far, Typst's collaboration backend ran on just one server. The collaboration backend makes sure that when you type in the project, all the other people currently viewing that project will see your new input in real time. That means, that when you hit the letter 't' on your keyboard, that server got a message with the letter you typed. Then, it would distribute it to all other people currently viewing this project. It would also eventually store the project with the added letter in permanent storage, so that it is still there when you next open it.

Why does it need to be one server? Well, that was the simplest way to make sure that that server knows about everyone else who is currently online in a particular project so that edits would get sent to everyone who's online. However, Typst has now reached a scale at which we need to distribute the load across multiple servers. You may have noticed long project loading times at peak times --- that's because our single collaboration server was too congested to immediately serve your request. On the flip side, on off-peak hours, the server was overprovisioned, meaning that it was beefier than it needed to be to serve all current users.

We have developed a new collaboration backend that allows us to run on multiple smaller servers that we can add and remove as demand changes over a particular day. This is the last part of our infrastructure to gain this capability to automatically scale out on demand. For you as a user, this means faster initial load times and more responsive typing when collaborating. It also means that opening a project in the Not connected state should occur less often. This new architecture will also allow us to launch new features for Typst Pro that would otherwise have had unreasonable performance impact on our collaboration backend.

We are also taking this opportunity to change how your browser communicates with our servers to cut down on the amount of data sent while online in a project and when loading it. This too, should result in faster load times and less data usage if you are using Typst from a metered mobile connection.

Finally, we are using the downtime to add IPv6 connectivity to Typst. This means that Typst will soon be now available to networks that do not have an IPv4 address and some devices will be able to connect to Typst with lower latency.

We will update you throughout the maintenance window through our social media feeds and Discord. Go to https://typst.app/socials/ to follow and get subscribed on your preferred platforms.

We are happy to announce that we’ve partnered up with someone who’s eager to change this: Dr. Alberto Corbi and the International Journal of Interactive Multimedia and Artificial Intelligence (IJIMAI) are leading the charge by becoming the first journal to not only accept Typst, but maintain their official template on Typst Universe. IJIMAI is a prominent Q2 journal focusing on Artificial Intelligence, Data Mining, Knowledge Management, Semantic Web, and Interactive Multimedia.

IJIMAI has an interdisciplinary bent — Dr. Corbi himself is a physicist, teaching at the Universidad Internacional de La Rioja (UNIR). With remote-first teams composed of researchers whose publication in IJIMAI might be their first point of contact with an automated writing system, lowering the barrier of entry is instrumental in facilitating their work.

In the end, this is what Typst is all about: The Typst language streamlines and simplifies automated writing and brings its benefits to a wider audience. Meanwhile, the Typst web app brings out the best in Typst with features like instant preview, while providing a familiar collaboration environment that's easy to dive into.

We want to thank Dr. Corbi from the bottom of our heart for supporting Typst by spearheading its introduction at IJIMAI, the first JCR-indexed journal to accept submissions authored in Typst. We also extend our gratitude to Dr. Elena Verdú Pérez, Editor-in-Chief of IJIMAI, who has also been instrumental in the introduction of Typst at the journal.

We'd like to encourage you to submit to IJIMAI if you work on AI, multimedia, or interactive systems. For technical support on the template, contact Associate Professor Alberto Corbi at alberto.corbi (at) unir.net or consult the project’s GitHub repository.

Contents

In this blog post, I'll walk you through the highlights of the release. If you prefer a more visual take on the topic, also check out the release video.

• Paragraphs and first line indent
• Better-looking outlines
• New curves
• Files and bytes
• Generating images
• Faster plugins
• Single-letter strings in math
• Font coverage control
• PDF file embedding
• A first look at HTML export
• Migrating to Typst 0.13
• Community Call

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

Paragraphs and first-line indent

The work on semantic paragraphs is what I'm most proud of in this release, but at the same time it's among the things that are least visible for users. What do I even mean with "semantic paragraphs?"

Let me explain. Up until now, Typst considered every piece of text you wrote as a paragraph — be it a single word in a page header, a figure caption, or a page number. Just like paragraphs, these things can have spacing, break across lines, etc. Layout-wise they are not all that different from paragraphs.

However, there are semantical differences. Only proper paragraphs should be counted when paragraphs are numbered (such as in legal texts). Only proper paragraphs should be announced by a screen reader as such. And even layout-wise there are differences; for instance, that only proper paragraphs should have first-line indent. While the layout routines for "just text" and a paragraph may be very similar, the second order effects of something being a proper paragraph are far-reaching.

In version 0.13, Typst finally gains a better understanding of this distinction. Whether something is a paragraph or just text is decided based on a few simple rules about which you can read in the updated paragraph documentation.

The most visible immediate effect of this work is that first-line-indent can now be applied to all paragraphs instead of just consecutive ones, closing the most upvoted Typst bug. Semantic paragraphs are also crucial for the in-development HTML export and for planned future work on PDF accessibility.

#set block(spacing: 1.2em)
#set par(
  spacing: 0.65em,
  first-line-indent: (
    amount: 1em,
    all: true,
  ),
)

= Chapter 1
In this text, the paragraphs are
all indented, without exception.

With `all: true`, the first
paragraph is affected as well.

Better-looking outlines

If you've created a table of contents with Typst's outline functionality before, you might remember that it always looked a bit bland. The default style had no indentation and rather tightly dotted leaders (leaders are the filler dots between a title and its page number).

In Typst 0.13, the outline gets a full facelift while also becoming easier to customize. The new automatic indentation nicely aligns all titles and numberings across the whole outline, long titles have better-looking wrapping behavior, and we fixed a number of bugs.

If you have a customized outline, check out the migration section for the outline to learn how to adapt your customization.

#set heading(numbering: "1.i.")

#outline()

= Introduction
= Methods
== Experiments
== Statistics
= Results
== T Experiment
== K Experiment
== V Experiment
== Additional experiments with extra length
= Discussion
= Conclusion

New Curves

Since Typst 0.2, you could draw Bézier paths with the path function. However, the input format of this function was rather arcane. Rather than specifying pen movements as in an SVG, you had to specify directly points with their two control points. Moreover, the path function had a fatal flaw: You could not close a path and then keep on drawing. This is necessary to draw a shape with cutouts, as depicated below.

The new curve function fixes these flaws. It provides an easier-to-understand and more expressive interface. We also used this opportunity to change the name from path to curve as we plan to repurpose the name path for a file path type in an upcoming release.

#curve(
  fill: blue.lighten(80%),
  fill-rule: "even-odd",
  stroke: blue,
  curve.line((50pt, 0pt)),
  curve.line((50pt, 50pt)),
  curve.line((0pt, 50pt)),
  curve.close(),
  curve.move((10pt, 10pt)),
  curve.line((40pt, 10pt)),
  curve.line((40pt, 40pt)),
  curve.line((10pt, 40pt)),
  curve.close(),
)

Thanks to @Emm54321 for working on this!

Files and bytes

Various functions in Typst load files, be it images, data loading functions, or plugins. Sometimes though, a little extra flexibility is needed, for example, to preprocess, generate, or inline data into a Typst document.

For this reason, there are also .decode variants on various of the functions, e.g. image.decode or json.decode. However, that approach didn't work so well when a path is expected in a set rule, as in set raw(theme: "light.tmTheme"). It also introduced duplication: All the properties of an image are also spelled out again in image.decode.

Typst 0.13 revamps file handling to improve this unsatisfactory situation. All places where a path is expected now also support raw bytes instead. Typst will always interpret a string as a path and raw bytes as data. When trying to decode an image from a string, thus make sure to first convert it to bytes. Converting to bytes is cheap as Typst will internally reuse the memory from the string. It will even remember that the bytes came from a string to make conversions back to a string cheap as well!

The existing .decode functions are now deprecated as they are not needed anymore. The .encode variants of data loading functions remain unchanged.

See @netwok for details.

#bibliography(bytes(
  ```bib
  @article{netwok,
    title={At-scale impact of the {Net Wok}},
    author={Astley, Rick and Morris, Linda},
    journal={Armenian Journal of Proceedings},
    volume={61},
    pages={192--219},
    year={2020},
    publisher={Automattic Inc.}
  }
  ```.text
))

Generating images

With the new byte-taking image function (and previously image.decode), you can generate images at runtime. However, the image function expects images in an encoded image exchange format like PNG or JPEG. Producing valid bytes for such a format in pure Typst code is prohibitively complicated. Meanwhile, plugins are unnecessarily bloated and slowed down if they have to include an image encoder.

To streamline image generation workflows, Typst 0.13 thus brings support for loading images from uncompressed raw pixel data. To that end, the format parameter of the image function supports a new form, where the channel encoding and pixel width/height of the image can be specified. This feature is crucial for better scientific visualizations — think things like heatmaps.

#image(
  bytes(range(64).map(x => x * 4)),
  format: (
    encoding: "luma8",
    width: 8,
    height: 8,
  ),
  width: 4cm,
  scaling: "pixelated",
)

Thanks to @frozolotl for working on this!

Faster plugins

In version 0.8, Typst gained support for WebAssembly plugins — one of the features that would very likely still be a little blue "feature request" label if not for our fabulous open source community. Since then, plugins have become the backbone of various community packages. They're great because they bring the power and package ecosystem of all the languages that compile to WebAssembly right into Typst.

They are also faster to execute than Typst code. Still, with heavy usage the time spent executing plugin code can make up a significant chunk of compile time. A simple way to improve this would've been to switch to a faster WebAssembly runtime (specifically, from wasmi to wasmtime). However, taking on a dependency on a WebAssembly runtime with just-in-time compilation¹ wasn't a spot we wanted to put Typst into. It would have reduced portability and security and increased the amount of third-party code Typst depends on by a lot.

There was another way to speed up plugins: Since 0.12, Typst's layout engine is multi-threaded. Plugins didn't profit from this though as they couldn't be easily replicated across threads. This is a limitation we're lifting with 0.13. Typst will now automatically run plugins in multiple threads without any changes from plugin authors. This is possible because we require (and also already required in the past) plugin functions to be pure. This means that we can execute plugin functions out of order without a visible effect. For cases where purity is too limiting, Typst 0.13 introduces the new plugin.transition API, which lets plugin authors deal with stateful operations in a sound way.

The work on speeding up plugins was prioritized through a Typst Open Source Support contract. If you're using Typst in production at your company and are hitting any road blocks, please reach out to us!

Single-letter strings in math

Since Typst's initial release, $ "hi" $ would generate the letters "h" and "i" in upright style while $ "h" $ would result in an italic "h". It's one of the longest-standing bugs, which is curious because it seems so easy to fix. Unfortunately, it was not. To see why, we need to take a look behind the scenes and understand how Typst views your equations.

In Typst 0.12 and lower, the x in $ x $ is a text element like any other text in your document. A string like "hi" is converted to content by becoming such a text element, too. While different syntactically, $ x $ and $ "x" $ thus used to yield identical content. Since x becomes italic by default, "x" did, too.

Changing that by itself wouldn't have been too hard, but there is a third guest to the party: Symbols. The pi in $ pi $ is a symbol value. Like strings, symbols were up until now converted to content by becoming text elements. This means they work both in math and normal text (as #sym.pi).

For a long time, the issue was thus blocked on finding a general solution to the text element ambiguity — perhaps introducing a new var element for math-y text. That story isn't fully written yet, but for 0.13 we really wanted to fix the issue at hand. For this reason, we attempted to find a minimal solution that fixes the issue while leaving our options for further improvements open.

The solution we came up with: Bare letters and symbols are now converted into an internal symbol element, which has auto-italics in math, but is transparently converted to normal text outside of math. Meanwhile, strings still generate text elements. With the planned unification of types and elements, this symbol element and the existing symbol type will naturally merge into one.

$ a != "a" $

Thanks to @wrzian for working on this!

Font coverage control

When text in different writing scripts is mixed, it's often important to have precise control over which text is typeset with which font. For example, Latin and Chinese text are almost always typeset with different fonts.

This is quite problematic for CJK (Chinese, Japanese, Korean) Typst users which often have text that mix their native language and English. Typst 0.13 takes a first step to improve this situation. With the new covers functionality, users can specify precisely for which character ranges a font should be used. This can, for example, be used to define in which font punctuation (which is present in both Latin and CJK fonts) is rendered.

The covers feature supports specifying a character set, either as a regular expression or one of the built-in ones. Currently, the only built-in set is "latin-in-cjk", which should be specified for a Latin font that is before a CJK font in the fallback list. In the example below, we can put Inria Serif first in the fallback chain while still having quotes render with Noto Serif CJK SC.

// Mix Latin and CJK fonts.
#set text(font: (
  (
    name: "Inria Serif",
    covers: "latin-in-cjk",
  ),
  "Noto Serif CJK SC"
))

分别设置“中文”和English字体

Thanks to @peng1999 for working on this!

PDF file embedding

With Typst 0.13's new pdf.embed function, you can attach arbitrary text or binary files to your PDF. These embedded files can then be browsed in PDF viewers or extracted programmatically by third-party tools.

When is this useful? One example, electronic invoicing, is ever more important as new EU legislation just came into force. While electronic invoices are typically in XML-based formats, it's often useful to still have a human-readable and printable invoice.

With PDF file embedding, the XML invoice data can be inserted into the PDF itself, forming a hybrid invoice. Currently, there is still one missing piece in Typst's support for this: The PDF metadata must identify the document as an E-Invoice to other applications. We plan to add support for embedding arbitrary metadata like this in a future Typst release.

Thanks to @NiklasEi for working on this!

A first look at HTML export

Saved for last is a particularly exciting topic: We've been starting work on HTML export! The feature is still very incomplete and only available for experimentation behind a feature flag, but there's already some stuff to see.

What works

Most of the markup and some of the other built-in functions like figure and table already produce the appropriate HTML. Our focus is on producing semantically rich HTML that retains the structure of the input document. The HTML output should be accessible, human-readable, and editable by hand.

The Typst document below

= Introduction
A *document* with some _markup._

- A list
- with elements

#figure(
  [A bit of text],
  caption: [My caption],
)

will produce the following HTML output:

<!-- html, head, and body omitted for brevity -->
<h2>Introduction</h2>
<p>A <strong>document</strong> with some <em>markup.</em></p>
<ul>
  <li>A list</li>
  <li>with elements</li>
</ul>
<figure>
  <p>A bit of text</p>
  <figcaption>Figure 1: My caption</figcaption>
</figure>

Typst cannot always produce the perfect HTML automatically. Instead, it gives you full control by letting you generate raw HTML elements:

#html.elem(
  "div",
  attrs: (style: "background: aqua")
)[
  A div with _Typst content_ inside!
]

<div style="background: aqua">
  A div with <em>Typst content</em> inside!
</div>

To make your document portable across PDF and HTML, we're also introducing a target function that returns the current export format (either "paged" or "html"). It is mainly intended for use in show rules, like below:

#let kbd(it) = context {
  if target() == "html" {
    html.elem("kbd", it)
  } else {
    set text(fill: rgb("#1f2328"))
    let r = 3pt
    box(
      fill: rgb("#f6f8fa"),
      stroke: rgb("#d1d9e0b3"),
      outset: (y: r),
      inset: (x: r),
      radius: r,
      raw(it)
    )
  }
}

Press #kbd("F1") for help.

<p>Press <kbd>F1</kbd> for help.</p>

The target function is contextual because the export target can vary within one compilation. How? With the html.frame function, you can lay out part of your HTML document as an inline SVG, using Typst's normal layout engine. Within such a frame, the compilation target is "paged" again, so that show rules produce the appropriate layout elements instead of HTML elements.

What's missing

A lot! For instance, currently, Typst will always output a single HTML file. Support for outputting directories with multiple HTML documents and assets, as well as support for outputting fragments that can be integrated into other HTML documents is planned.

Typst currently also doesn't output any CSS, instead focusing fully on emitting semantic markup. You can of course write your own CSS styles and still benefit from sharing your content between PDF and HTML.

In the future, we plan to give you the option of automatically emitting CSS, taking more of your existing set rules into account. More generally, we have a lot of plans for HTML export! Visit the tracking issue to learn more about them.

Try it!

In the CLI, you can experiment with HTML export by passing --features html or setting the TYPST_FEATURES environment variable to html. In the web app, HTML export is not yet available. It will become available once we think it's ready for general use.

You can also use HTML export with typst watch. Typst will then automatically spin up a live-reloading HTTP server that serves your document.

$ typst watch hi.typ --features html --format html --open

watching hi.typ
writing to hi.html
serving at http://127.0.0.1:3001

[20:31:09] compiled with warnings in 1.52 ms

Sponsorship

Work on Typst's HTML export is sponsored by NLNet. We are very grateful for their support! We also want to thank external contributor @01mf02 with whom we've thus far collaborated on HTML export through the NLNet grant. Unfortunately, we and him have since parted ways over technical differences. Nonetheless, we plan to increase the time and resources we put into HTML export, and we are very happy to have NLNet's continued support in this endeavor.

Migrating to Typst 0.13

Typst 0.13 ships with a number of deprecations and breaking changes. The changelog has a full account of all changes, but in this section you'll learn how to deal with the most common kinds of breakage.

Type/string compatibility

In Typst 0.8, types were promoted to proper values. As a result, type(10) directly returns a type instead of a string since then. To make this change less disruptive, we also introduced a temporary compatibility behavior where types could be used like strings in some contexts (e.g., int == "integer" would be true). For implementation reasons, we did not add a warning for this at the time. We're rectifying this now and adding a warning to shake out remaining reliance on this behavior. With Typst 0.14, the compatibility behavior will be fully removed.

// Typst 0.8+ ✅
#{ type(10) == int }

// Typst 0.7 and below ⚠️
#{ type(10) == "integer" }

Decode functions

The image.decode function and the .decode variants of data loading functions are now deprecated. You can instead directly pass bytes to the respective top-level functions instead. Read the section on files and bytes to learn more.

// Typst 0.13+ ✅
#image(bytes("<svg>..</svg>"))

// Typst 0.12 and below ⚠️
#image.decode("<svg>..</svg>")

Outline

The changes to the built-in outline (table of contents) improve the out-of-the-box style and customizability. Unfortunately, they also break some existing outline customizations.

First of all, the fill argument moved from outline to outline.entry. If you get the error "unexpected argument: fill", adjust your code as shown below:

// Typst 0.13+ ✅
#set outline.entry(fill: none)

// Typst 0.12 and below ❌
#set outline(fill: none)

Because the fill property is now on the entry, it can also be configured for individual outline levels, like this:

#show outline.entry.where(level: 1): set outline.entry(fill: none)

In light of the changes to paragraphs, outline entries now show themselves as blocks instead of lines of text. This means spacing is now configured via normal show-set rules for block.spacing.

// Typst 0.13+ ✅
#show outline.entry.where(level: 1): set block(below: 1em)

// Typst 0.12 and below ⚠️
#show outline.entry: it => {
  it
  v(1em, weak: true)
}

In Typst 0.12 and below, outline entries expose a few fields like .body and .page that are useful for writing an outline entry show rule. These fields were derived from other fields for your convenience. Typst 0.13 makes this more explicit and idiomatic by turning them into methods. Read the documentation on outline customization for more details on how to use these methods.

// Typst 0.13+ ✅
#show outline.entry: it => {
  ...
  it.page()
}

// Typst 0.12 and below ❌
#show outline.entry: it => {
  ...
  it.page
}

Paths

The path function is superseded by the new curve function. The curve function has an easier-to-understand interface that's closer to how SVG and the HTML canvas work. Read the curve function's documentation to learn how to express existing paths with the new function.

// Typst 0.13+ ✅
#curve(
  fill: blue.lighten(80%),
  stroke: blue,
  curve.move((0pt, 50pt)),
  curve.line((100pt, 50pt)),
  curve.cubic(none, (90pt, 0pt), (50pt, 0pt)),
  curve.close(),
)

// Typst 0.12 and below ⚠️
#path(
  fill: blue.lighten(80%),
  stroke: blue,
  closed: true,
  (0pt, 50pt),
  (100pt, 50pt),
  ((50pt, 0pt), (40pt, 0pt)),
)

Patterns

The pattern type was renamed to tiling. To migrate, simply replace pattern with tiling. No further changes are necessary. The name pattern remains as a deprecated alias in Typst 0.13, but will be removed in an upcoming release.

Why the rename? For once, the name pattern was very generic. The name tiling is more closely associated with what it expresses. Secondly, we're considering to repurpose the name pattern for what today are selectors once elements and types are unified.

// Typst 0.13+ ✅
#rect(fill: tiling(..))

// Typst 0.12 and below ⚠️
#rect(fill: pattern(..))

Removals

We also removed a number of things that were already deprecated and warned for in Typst 0.12. This includes the

• style function and styles argument of measure; use a context expression instead
• state.display function; use state.get instead
• location argument of state.at, counter.at, and query
• compatibility behavior where counter.display worked without context
• compatibility behavior of locate

Refer to the Migration section of the Typst 0.12 announcement post to learn more about how to migrate away from these functions.

Community Call

That's it for Typst 0.13. We hope you're just as excited about the release as we are!

We're hosting a community call on Discord on Friday, March 7th. Join us to share your experiences with the new version and to chat with the community!

With Typst 0.12, we set out to make meaningful progress on Typst's foundations. We took the last six months to work not just on shiny things, but to truly move the core systems of Typst forward. A lot of this work bears fruit today: Typst 0.12 ships with long-requested layout features, improved PDF output, and even better performance. But more happened than is visible at the surface: We also laid important foundations for upcoming work on things like HTML output, accessible PDFs, and more powerful layout.

In this blog post, I'll first walk you through the highlights of this release, then showcase some of the most exciting internal improvements, and finally explain how to migrate your existing documents to Typst 0.12.

Better layout

The headline feature of this release are floating figures spanning across multiple columns. By specifying scope: "parent" on a figure (or any floatingly placed element), you instruct Typst to place it across all columns.

Delivering this seemingly innocuous feature forced us to make a choice: Hack it in or build it right. We chose the latter option and fully re-engineered the core layout engine. This was obviously a lot of effort (and the main reason for this very slow release cycle). The good news is that it brings many more benefits than just multi-column floats. For example, the new engine brings improvements to widow/orphan prevention for headings (no more headings at the bottom of the page!) and fixes various issues with footnotes. It also lays the groundwork for future features like side floats and text flowing around shapes and images.

#set page(columns: 2)
#set columns(gutter: 15pt)
#set par(justify: true)

// In a real document, this would of course
// be in your template!
#place(
  top + center,
  float: true,
  scope: "parent",
  text(13pt)[*Essay on rectangles*]
)

#figure(
  placement: bottom,
  scope: "parent",
  rect(width: 70%),
  caption: [A normal rectangle],
)

Rectangles are often considered a superior
shape because of their versatility,
simplicity, and practicality. Their four
right angles and straight sides make them
easy to stack, arrange, and tile without
wasting space, making them ideal for
architecture, design, and packaging.
Rectangles also provide a stable and
balanced structure, whether in frames,
screens, or rooms, maximizing usable area
...

Another widely requested layout feature we're shipping in Typst 0.12 are line numbers. Typst can now add numbering in the margin for all text in your document, no matter how deeply nested. With line numbers, other people always know exactly which line you're talking about when you're reviewing their work. Line numbers can be flexibly enabled, tuned, and disabled for individual parts of your document. Refer to the par.line documentation for all the details.

#set par.line(numbering: "1")

Line numbers are useful when you're
submitting a document for review.

They are a great way to review PDFs as
reviewers can easily state which piece of
the document their comment applies to.

Though, thinking about it, wouldn't it be
nice if they could just leave a comment
directly --- let's say in a collaborative
web app?

There are various other layout improvements and I encourage you to read the changelog for all the details. There's one more thing I'd like to highlight here because it seems like a minor detail, but it actually improves Typst's output quite meaningfully: Tuned hyphenation.

When justification is enabled, Typst uses a paragraph layout algorithm that optimizes for a uniform visual appearance of paragraphs, only hyphenating words when necessary. In previous Typst versions, this hyphenation was somewhat over-eager, resulting in too many hyphens being inserted. In Typst 0.12, we tuned the costs involved in the layout engine's decision making and added new logic that penalizes hyphens close to the edges of a word.

Better PDFs

Typst 0.12 brings crucial improvements to PDF output:

• Reduced file sizes: PDFs typically embed the necessary fonts for rendering. Fonts can be quite large, so it's important to reduce the size of fonts by removing all glyphs that aren't used in the document. Typst 0.12 ships with a new, much more space-saving subsetting implementation (particularly for .otf fonts) that also fixes a few important bugs leading to wrong printer output.

• Support for emoji: Due to its age, PDF unfortunately does not natively support emoji fonts. They must instead be emulated with native PDF mechanisms. There are ✨ four ✨ competing standards for emoji fonts, but the good news is that Typst 0.12 ships with support for all of them.

• PDF/A: The various PDF/A standards define stricter rules for PDFs to ensure long-term compatibility. More and more institutions require PDFs to comply with these rules. Typst can now emit files that comply with the PDF/A-2b profile. In the web app, there's a new PDF/A checkbox in the "File > Export As > PDF" menu and on the command line, you can pass the argument --pdf-standard a-2b. Note that this is only a first step; we want to support more PDF profiles in the future. In particular, we plan to ship PDF/UA support, which makes PDFs friendly to people who rely on assistive technologies.

Better performance

There is one fundamental law of compiler development: Your compiler can never be too fast. So we made Typst even faster with 0.12.

The most decisive improvement comes from multi-threading. Typst 0.11.1 was almost fully single-threaded. Meanwhile, Typst 0.12 can, under the right circumstances, make use of all your CPU cores. For now, this multi-threading operates on explicit pagebreak boundaries (note that the page breaks can be generated by show rules, they just need to be there). The speedup doesn't quite scale linearly with the number of CPUs, but we've observed typical speedups of 2-3x on normal hardware. But if you're a diligent writer and start your chapters on a new page, you can look forward to saturating your 16-core CPU. 🏎️

Aside from multi-threading, we've implemented a novel approach for faster yet still optimal layout of justified paragraphs. Depending on the paragraph length (it's better for shorter paragraphs), this can bring quite the speedup. We've observed up to 6x performance increases for documents consisting primarily of justified paragraphs.

We also tweaked incremental compilation to alleviate some missed caching opportunities, keeping your live preview snappy.

Better internals

While many things are going on at the surface, maybe even more changed internally. We used the last six months to rework and rewrite various subsystems of the Typst compiler, making them ready for the future:

• A new system for identifying elements made multi-threading of the layout engine possible.
• A rework of how Typst handles page layout and styling fixed a ton of styling and introspection bugs.
• We completely rewrote the subsystem that resolves your set and show rules in preparation of the upcoming HTML export.
• Paragraph layout was optimized for speed and refactored for correctness.
• The new flow layout engine not only enabled two-column figures and fixed many bugs, it also made a lot of progress towards future layout features. If you're interested in the details, I wrote a bit more about layout on my personal blog.

Migrating your documents

The release contains a few breaking changes, which might affect your documents. The most important change: If you have two-column documents that use the columns function at the top level, you should migrate those to using a page set rule instead. This ensures that columns interact appropriately with floating figures, footnotes, and line numbers. See the relevant section of the page layout guide for more details on this, in particular on how to create a two-column title section in the new system.

// Typst 0.12 ✅
#set page(columns: 2)
#set columns(gutter: 20pt)

// Typst 0.11 and below ❌
#show: columns.with(2, gutter: 20pt)

The second important change relates to paragraph spacing. Instead of needing a show-set rule for block spacing, you can now set paragraph spacing directly. This simplifies a very common configuration option and brings it in line with how line spacing is already configured. Note that spacing for non-paragraph blocks (like headings) continues to be configured through show-set rules. For the curious ones, further motivation for these changes is given on GitHub.

// Typst 0.12 ✅
#set par(spacing: 1.5em)

// Typst 0.11 and below ❌
#show par: set block(spacing: 1.5em)

Typst 0.12 also deprecates various introspection functions that were superseded by Typst 0.11's context system.

// Typst 0.11+ ✅
#context query(heading)
#context here().position()

// Typst 0.10 and below ❌
#locate(loc => query(heading, loc))
#locate(loc => loc.position())

Many packages are affected by these deprecation warnings. Visit Typst Universe to check whether your favorite packages have already released a new version that switches away from the deprecated functionality. Note that warnings in packages are automatically hidden by the web app, but can be shown by clicking on "Show warnings in packages" in the Improve Panel.

That's it for this overview! Visit the comprehensive changelog for all the details about what changed in Typst 0.12.

But as soon as our Typst Guys got a good look at the faces of the other Typst Guys, it became apparent that that was not the case. They were frowning and slouching and seemed generally miserable.

“We are so glad you are here to help us.” The leader of the other Typst Guys approached the eldest. “Our user is very harsh on his students and we don’t know what to do! Nothing we tried convinced him to be more kind.”

“I’m sorry, but we are not here to help your user. We are here to help our student”, said the eldest.

“But we can’t do it alone!”

Silence followed. Nobody knew where to go from here. The eldest was uncomfortable with the entirety of this mission. The youngest was too excited to think straight. The lazy Typst Guy again sat in a corner and the strongest felt it was the perfect time to do some push-ups. The others of the student’s Typst Guys all stared at one another.

“Would you help us if we helped you?”

“That depends on what you have to offer us”, said the eldest to the leader of the other Typst Guys and felt bad about how cold that sentence sounded. But the eldest had to look out for their team and could not risk overworking the student’s Typst Guys.

“Our user has written a detailed outline of the report with which he tasked his students. We would be willing to show it to you. Even so the report won’t write itself, but if you manage to memorize what the outline says, it will make finishing the paper in time a lot easier.”

This offer was much better than any of the student’s Typst Guys had expected. In fact, it was too good to refuse. Our Typst Guys huddled together and quickly discussed the situation, but they were all in agreement.

“We will help you”, proclaimed the eldest in a tone of voice that made the youngest laugh because it sounded too serious for the occasion. The other Typst Guys thanked them and disappeared to get the outline. In the meantime, our Typst Guys got to look around.

On the inside the professor’s device was almost identical to that of the student. Apparently, they were using the same browser and the same type of computer. But on the outside, in the analogue world, everything was different. The professor looked nothing like the young student who still suffered from his teenage acne and a naïve baby face. The professor had gray hair, a mustache and wore glasses. He didn’t look like the villain the eldest had imagined. The professor’s room was more spacious than that of the student and in the back, near a window, there was a Christmas tree already decorated with a variety of ornaments.

“The outline is ready for you”, said the leader of the other Typst Guys, who had just come back and presented the document. All the student’s Typst Guys memorized as much as they could. The professor valued precision and structure. And there were a few important points that he wanted all his students to touch on in their papers. Those seemed to be the most important pieces of information to the Typst Guys.+

“Now it is your turn to help us.”

“What have you tried so far?”, asked the eldest.

“We tried to communicate with him on the loading screen. We showed him a tip that he was too strict and that his student’s would stop enjoying their studies and how sad that would be. After all, he shares a common interest with them. They should get along! But he wouldn’t read them! We then sent him newspaper articles on kindness, which didn’t work either. Maybe he knows he’s mean. Lately he’s been crying a lot and we couldn’t console him. We think he might be upset because he’s going to be alone on Christmas. From what we gather, he has recently lost his mother to a long illness.”

That explained a lot. And the Typst Guys could not help but feel bad for the professor. Sure, he had been unfair to his students, but he was going through a tough time in his life.

“Does he need a friend?”, asked the youngest.

“It appears he does”, said the eldest. “But our field of expertise is in typesetting, not matchmaking between friends.”

“Where does one make a friend?”, asked one Typst Guy.

The lazy Typst Guy had made a lot of friends at a dance club that they frequented after drinking too much caffeine (energy drinks were the devil). The strongest had made friends at the gym, while the eldest had his childhood friends to talk to on the phone.

“I make my friends online”, said the youngest. “Maybe there is such a thing as an internet forum for lonely professors?”

A quick search revealed that indeed, such a thing existed. The student’s Typst Guys left it to the other Typst Guys to familiarize the professor with it. He was their user and therefore theirs to deal with. The student’s Typst Guys were done here. It was about time they left and finished the student’s report.

Everything was much easier now that they had seen the outline. The morning of Christmas Eve they were finally done. No additional unreasonable demands from the professor had disrupted the writing process.

The student passed with flying colors and got to enjoy the rest of the holidays. The professor made friends on the internet forum and was generally in a much better mood. He had still been alone on Christmas, but when he was not grading papers, he was online talking to the other lonely professors and enjoying himself. The Typst Guys would soon be assigned another project, but for now they were pleased with themselves and had gone back into the cloud where they lived happily ever after.

Thank you for reading and stay tuned for the final days of 24 Days of Christmas. Happy Holidays!

Our student was still doing their best, but they had lost a lot of steam and it became clear that the paper was wearing them out. They had stopped getting dressed in the morning to put them into the right mood to write and they no longer seemed quite as focused, sometimes mindlessly scrolling through the document. It was only a matter of time before they tossed aside their vegetable snacks and started gnawing on another chocolate Santa.

“Where do we go from here?”, asked one of the Typst Guys. Nobody knew an answer. The obnoxious kitten song would not work twice. Try it a second time and it would only upset the student souring the relationship between them and the Typst Guys in the process.

“Let’s just keep setting letters for them”, said the eldest, fully aware that this would not solve their problem. “It will give us some time to come up with a plan.”

The others nodded in agreement.

To everyone’s dismay, nobody could think of what to do before the breaking point finally came. The professor sent out an e-mail informing his students that he had changed his mind about the report. He did not give them a later deadline or let them know that they did not need to write a minimum of thirty pages after all. Fifteen still wouldn’t do. But what he did do was notify them of the fact that he had thought about the content of the report and now wanted his students to research different subjects than he had previously. This undid all the work our student and the Typst Guys had done. The student, upon reading the e-mail, curled up in a corner, hid their face and was presumably crying.

“How come the professor is so cruel?”, asked the youngest of the Typst Guys. The older Typst Guys were well aware that this was the unfortunate way of the adult world. They decided not to answer the youngest. It seemed to be for the best.

“I will give the professor a piece of my mind”, said the strongest but also the most impulsive of the Typst Guys and began writing the professor an e-mail.

“No, you will not do that.” The eldest reacted immediately and pulled the strongest Typst Guy out of the web browser back into Typst before the strongest could do any harm. This was not their situation to escalate. It was up to the student to deal with the professor as they saw fit.

“Do you think the professor uses Typst?” The youngest again asked another question. However, this time around the Typst Guys weren’t too sure of the answer.

“We could call headquarters and ask if they know.” This was a great idea by another one of the Typst Guys. The eldest immediately made the inquiry only to find out that indeed the professor did use Typst.

“That means that he has friends of ours working for him”, concluded the eldest, “We should talk to them.”

And so, the Typst Guys packed up, left the student a notice that they would be back soon and went home into the cloud. From there they took their helicopter into the professor’s computer. The eldest had never entered the device of a user that had not been assigned to them. Clearly, they were in over their heads.

Stay tuned to 24 Days of Christmas and don't miss what happens next. Happy Holidays!

Our student had to achieve a passing grade on this specific report, if they wanted to be eligible to write a master’s thesis. And while the student was well aware of their situation, they could just not get themselves to start working on the project. There were much nicer things to do: They could go ice skating with friends. They could take a stroll through the snow. Or they could sit on their sofa and not move at all unless their stomach or bladder called.

However, the student had already done one thing: They had opened Typst, the app, about which they had heard from a friend, and had left the screen of their computer on. It was their first time using the app to write a paper, but they had already spent some time playing around with it and felt confident enough to use it.

To follow this story, this is what you need to know: Whenever a student – or anyone for that matter – opens Typst, the Typst Guys are alerted via a call to their red rotary phone. When they are not hard at work, the Typst Guys live in the cloud. Everything is soft and cozy and comforting up there and the Typst Guys do not like to leave their cloud, but they love helping the Typst users even more than they enjoy their time off work. And when they get to fight a wicked professor in the process, they can hardly contain their excitement to do so.

The Typst Guys were carefully monitoring the student, waiting for their chance to help them. And since the student had not moved the mouse cursor once in the past hour or had done so much as type a single letter, it appeared that the time of the Typst Guys had come. After all, something had definitely gone awry.

The Typst Guys were quick to understand that the student was procrastinating and not working on their report. They could not wait any longer, for the student was losing precious time and decided to take action. Anything to motivate the student and get them back to writing their paper.

“We should call out to them!,” blurted one Typst Guy.

“No, we should whistle, because whistling makes a much nicer sound,” said another.

Both of these ideas were shut down by the eldest and wisest Typst Guy, because no matter what noise they made, the student would not be able to hear them through the screen.

The youngest of the Typst Guys had another idea: “We could look for motivating videos online and get the student working that way.”

The other Typst Guys loved it. “How smart!”, exclaimed one of them. “Let’s get to it!”, another.

The Typst Guys did their best. They made sure to match the videos to the situation of the student. Some of the titles were How to study consistently or Follow these steps and you will never procrastinate again. And the favorite of the eldest: Why older generations worked harder in their youths and why you should too.

The student did not seem impressed. They quickly closed the tabs with the videos that the Typst Guys had chosen for them. To make matters worse, the student then got to eating a chocolate Santa, seeming even less interested in their report than before.

The laziest of the Typst Guys, who up to this point had been idling in a corner not engaging in the conflict, finally chimed in: “Why don’t we find the most obnoxious song on the internet and play it on loop until the student gives in?” Since this proposal came from the most slothful, most inert of the Typst Guys, it had to have some merit to it: If the lazy Typst Guy didn’t know how to motivate someone, no one did. Hence the Typst Guys gave it a try.

They found an overly auto-tuned, aggressive song of a kitten singing in a high-pitched voice, repeating nothing but one single sound (maybe a meow, but the Typst Guys weren’t too clear on that). The student closed the video. The Typst Guys re-opened it. The student closed it once more. And the Typst Guys again re-opened it. This went on for a little while, until the Typst Guys typed GET TO WORK! into the Typst App, while the song was still playing. Finally, this did the trick.

The student looked defeated, let out a deep groan and began to add their bibliography. The Typst Guys had become an ally to the student in the fight against the perpetually disgruntled professor and had successfully overcome the first obstacle. But seeing how poorly the student did with their bibliography, it became obvious that the Typst Guys had more work ahead of them in the coming days until Christmas.

Stay tuned to 24 Days of Christmas and don't miss what happens next. Happy Holidays!

Colors: Rework and new color spaces

Before we can talk about gradients, we need to talk about colors. In the previous version of Typst, you may have noticed that colors were sometimes a bit off. This was due to the fact that Typst was not in fact using the sRGB color space. Instead, Typst was using an approximate color space because sRGB is not available in PDF. Additionally, the number of color spaces supported by the PDF standard is very limited. This meant that to prepare Typst for gradients, I had to rework the entire color system. This involved a fairly massive pull request (#2171), which introduced a number of new color spaces: hsv, hsl, oklab, and linear-rgb. It also introduced better color reproduction by using ICC profiles to make rgb and luma more accurate.

But how did we implement these color spaces when PDF does not support them out of the box? The answer is simple and still makes me shiver: They are implemented using PostScript functions --- very long, very complicated PostScript functions. The PostScript language is the language that underpins the PDF files we all know and love tolerate. It is a stack-based language that is quite powerful, but also hard to use. As it happens, color conversion functions, while being part of the PDF standard, cannot use other functions and have access to a very limited number of instructions. This means that you cannot call subroutines, use loops, or even use variables. This makes the implementation of these functions very hard and very long. For example, the Oklab to linear-RGB conversion function is around 200 instructions long. I painstakingly wrote it by hand and had the displeasure of debugging it.

With these changes, and more specifically the introduction of ICC profiles, colors in Typst will now look the same regardless of the device or reader you are using.¹ This is a big step forward allowing for your documents to look more consistent and look better on a wider range of devices. These changes also introduce improved color space conversions and new features such as the ability to rotate the hue, saturate, and desaturate colors.

Perhaps the most important change is the introduction of the Oklab color space. This color space is a perceptually uniform color space, meaning that the distance between two colors in the Oklab space is proportional to the distance between these two colors as perceived by the human eye. Perceptual uniformity is a very important property for data visualization, as it means that the colors will be perceived as being equally different from each other. This is not the case for other color spaces, such as sRGB. For this reason, Oklab is now the default color space for gradients and color mixing. Additionally, it has the advantage that when printed in grayscale, the colors will still be distinguishable, a feature that is necessary for publishing scientific papers and desirable for accessibility of documents.

A primer on gradients & API overview

Color gradients are used in many places without necessarily being noticed. While you may be most familiar with the timeless Word Art we all created as kids, they are also prevalent in data visualization and other artistic endeavors. In the context of Typst, we chose to stick to the most common gradients for now: Linear gradients, radial gradients, and conic gradients. Additionally, we chose an API similar to CSS gradients to make it easier to use for people familiar with web development.

#rect(
  width: 100%,
  height: 30pt,
  fill: gradient.linear(
    ..color.map.rainbow,
  )
)

From this first example, we can already see a few things. First, gradients are applied in the same way as a color, using the fill or stroke properties. Second, gradients are their own type, gradient, and are created using constructor functions (in this example linear). As we will discuss later on, Typst also ships with a number of predefined color maps that can be used to quickly create gradients. In this example, we are using the rainbow color map.

#set align(center)
#circle(
  radius: 50pt,
  stroke: 2pt + gradient
    .conic(..color.map.rainbow)
    .repeat(2, mirror: true)
)

You can also use gradients as the stroke of a shape. In this example, we are using the conic which is a gradient that rotates around a center point. We are also using the repeat method to repeat the gradient twice, and the mirror option to mirror the gradient making it a nicer continuous pattern.

These first two examples show how gradients can be built up from simple components in a composable way. Additionally, gradients support several features that will become relevant in the following sections: Sharp stops, direction, and sampling.

#rect(
  width: 100%,
  height: 30pt,
  fill: gradient
    .linear(black, yellow, red)
    .sharp(3)
)

We can create gradients using a list of colors, and if we do not specify any other options, these colors will be evenly distributed along the gradient. In this example, we are using the sharp method to let the gradient have three distinct stops instead of a smooth transition, creating the Belgian flag (my home country).

#rect(
  width: 100%,
  height: 40pt,
  fill: gradient.linear(
    angle: 30deg,
    (red, 0%),
    (blue, 20%),
    (green, 80%),
    (purple, 100%),
  )
)

Similarly, we can specify the stops of a gradient using arrays of two values: A color and a ratio. The ratio is a number between 0% and 100% that specifies where the color should be placed in the gradient. Note that the colors must be in ascending order of ratio. We can also specify either the direction or the angle of the gradients. In this case, we are using the angle option to specify the angle of the gradient and create an ugly rainbow.

The final, and perhaps most important feature of gradients is the ability to sample them at a given point. This is useful for data visualization, as we will see later on. This is done using the sample function. It will clamp its argument within the range 0% to 100%.

#(gradient
  .linear(red, blue)
  .sample(50%))

You can also specify the area the gradient should cover with the relative argument. It can be either "self" or "parent". The default mode is "self", which means that the gradient's bounding box will coincide with the bounding box of the shape or element itself. When set to "parent", the gradient instead becomes relative to the parent container (a surrounding box, block, page, or similar construct). In the example below, you can see a gradient being used as the fill of a rectangle. The gradient is relative to the page since the page is the closest ancestor container.

#align(
  center + horizon,
  rect(
    width: 80%,
    height: 30pt,
    fill: gradient.linear(
      red,
      blue,
      relative: "parent",
    ),
  )
)

You can also use gradients on text as a nice effect. This is done by setting the fill property of the text to a gradient. Note that, on text, only the "parent" relative is currently supported and it is used by default. We made the decision, as can be seen in the tracking issue, to only support that mode for now. This is because the "self" relative on text is equivalent to per-glyph gradients, which are not very useful, very heavy in terms of file size, and incredibly difficult to get right.

#set text(fill: gradient.linear(
  ..color.map.rainbow,
))

A famous Chinese #box[poem]
about the hard work of farming:

#box[
  李绅《悯农》
  锄禾日当午，
  汗滴禾下土。
  谁知盘中餐，
  粒粒皆辛苦
]

Data visualization: Color maps

An important part of visualizing data is the ability to map a value to a color. You may not have noticed it, but a lot of research papers use colors to represent a value. Below you can see an example from Google that shows a color map being used to represent the distance from an object to the camera.

This is a very common technique, but it is not without flaws. The most common color maps used are the rainbow and the jet color maps. These color maps are not perceptually uniform, meaning that the distance between two colors is not proportional to the perceived difference between these two colors. This means that parts of your data can be misrepresented and that the colors will not necessarily be distinguishable by people with color blindness or when printed in grayscale. This is why Typst ships with a number of color maps that are perceptually uniform, and only one that is not (rainbow). Below you can see the complete list of color maps that Typst ships with:

I would recommend using the ones that fit your needs the best, but if you are unsure, I would recommend using the inferno and viridis color maps. These were designed specifically to be perceptually uniform and are commonly used in scientific papers. The rainbow color map is not suitable for data visualization, but it is still useful for artistic purposes.

You can easily use these maps by using the sample method on a gradient. This method will return the color at the given ratio. This means that you can simply map your values within the range 0% to 100% and use the result as the color of your data point. Below you can see an example of this technique being used to visualize the Mandelbrot set, inspired by @SeniorMars' experimentation.

With the awesome cetz package having more and more plotting features, I cannot wait to see what people will do with Typst, gradients, and data visualization. All of the tools are there, all we now need is for people to experiment and create using them. Science will never have looked so good.

What if we had a standard document format?

Now, it is time to discuss my dwindling sanity brought to you by the PDF standard. As you may know, PDF is a rather old standard, having been around for longer than I have been alive. As such, you would expect that it would have a well-defined and ubiquitous support of its features. Unfortunately, this is far from reality and, as it turns out, PDF readers are a hit or miss when it comes to supporting the features needed to implement gradients in a consistent way. This is why I had to implement a number of workarounds to make sure that gradients would work as expected in most readers.

The first issue I encountered was that the PDF standard defines color conversion functions in a very unique way. These functions are not allowed to use other functions and are not allowed to use variables which meant programming the entirety of the conversion functions using the stack. This is not a big deal, but it does make the code harder to read and debug. The second issue I encountered was that the code must be wrapped in curly braces { and }. This is not a big deal either, but figuring this out required untold hours of debugging as some readers would work, and others would not. Finally, for some reason, the PDF standard only allows the range of values to be between 0 and 1 when passed to these functions. This is a big deal because it means two things: First, we must normalize all color components before writing them to the file. Second, most readers don't care about this, but some do. Which meant that when working on improved color support, I only encountered this issue much later on, and it took me a while to figure out what was going on.

The first gradient type I implemented were linear gradients which were pretty uneventful. Using the existing code in pdf-writer and svg2pdf, they were quickly implemented requiring little in the way of workarounds. The second gradient type is the radial gradients, which are also pretty easy to implement since they are natively supported. So far so good, after the debacle that was color support, we now have two gradient types that are easy to implement and work as expected. Surely the third and final kind will be just as easy to implement, right?

Wrong! The conic gradient type is the most complicated to implement, and the most complicated to make work across all readers. The reason for this is that PDF does not support it natively. This means that we have to implement them using a combination of other features that are not necessarily intended for this purpose. I tried many different techniques, not all of which worked.

The first technique I tried was using a sampled pattern. This is equivalent to using a picture of the gradient. This worked, but it has several issues. Chief among them is that it leads to incredible bloat in the file size. This is because the gradient must be sampled at a very high resolution or we risk running into the second issue: Pixelation. Since we are pre-sampling the gradient, we are limited by the resolution of the image. This means that if we want to have a smooth gradient, we need to sample it at a very high resolution.

The second technique I tried was using a PostScript function to draw the gradient. This is a function that takes in an X-Y coordinate and computes the color at that point. This is a very elegant solution that works very well. Indeed, the idea would have been to have a function that takes in the X-Y coordinate and returns a sample in the range 0% to 100%. Then, we would use a shading function to map the sample to a color. This is even better because it allows us to reuse the entire logic for linear and radial gradients. Unfortunately, several readers do not support this feature. This meant that we were back to the drawing board.

The third technique, and the one we ended up sticking with, is the Coons patch method. A Coons patch is a kind of geometric construct defined by four points and eight control points. It can be used to depict three-dimensional geometry. In this case, we are using it to create a circle. Initially, I would calculate a value in the range 0% to 100% proportional to the angle. Then, just as before, we can use a shading function to map that value to a color. This meant that we were introducing only four Coons patches (one for each quadrant) and reusing the logic of other gradient types. Great!

Well not so fast buckaroo, you forgot to ask our corporate overlord: Apple. Indeed, they have their own PDF reader which is generally very good. Unfortunately, in their infinite wisdom, they do not support using a shading function for color mapping when using Coons patches. And since they have no feature request page (there is one on Apple's website but I never got any follow-up) nor issue tracker for this product, it may never get implemented.

This means we need a fourth technique? Not really, as I previously hinted at, we can still use Coons patches, but we need to create at least as many patches are there are stops in the gradient. This leads to larger files than the other techniques and requires duplication of the logic but it works in all readers we have tested so far.

I honestly feel like PDF is not a good standard. While having an official, agreed-upon standard, most readers have quirks and limitations leading to more complex export logic than should be needed. Additionally, as we will explore in the next section, PDFs are really hard to debug.

Debugging PDF

As it turns out, debugging PDF files is really difficult. In this section, I will introduce the tools I used to debug the test files generated throughout this project because I believe this is of interest to the wider community and other Typst contributors. There are four tools in particular that are of interest for PDF debugging:

• PDF Object Browser is a tool maintained by the PDF.js people that allows you to browse the tree-like object structure in a PDF file. This is useful to compare your PDF file with a reference file and see what is different. It is also useful to see what is in the file and how it is structured.
• GhostScript is an interpreter for PostScript that allows you to test your PostScript functions. You can also use its prepress feature to pre-process PDF files. Sometimes pre-processing a PDF file will either give you a mostly human-readable error message, or it will silently fix the error which you can then reverse engineering using the PDF Object Browser.
• XPDF Reader is a very old PDF reader, but it is also the only one I know of that actually gives meaningful error messages when it encounters issues in a PDF file. This can allow you to debug some features that would silently fail in other readers.
• mutool is a series of tools that can help you debug PDF files.

Finally, try and use existing tools such as Word, Adobe Illustrator, and others to create PDF files with the features you're trying to implement and compare them with your own files. This can help you figure out what is wrong with your files and how others have tackled the same issues.

SVG and the missing gradient

As you may know, Typst supports SVG export. And as you may have guessed, SVG also supports gradients. This makes the implementation of gradients in SVG rather simple in theory. In practice, it is a bit more complicated. The reason for this is that SVG does not support conic gradients and does not provide as much control over color spaces as a PDF does.

For conic gradients, this requires a bit of trickery. Most guides on the internet suggest using a <foreignObject>, plopping a <div> in there and using CSS. Because for some reason, CSS supports conic gradients but SVG does not. Why the SVG standard made such a decision is beyond me, but it is what it is. You might expect that they would be included in the SVG 2.0 spec but no, it's not there either. Additionally, most SVG readers will not enjoy you adding HTML in the middle of their SVG files. This means that we need to find an alternate solution: Enter triangles, lots and lots of triangles.

Below is a small demonstration of how Typst is implementing conic gradients in SVG. The idea is to draw a bunch of triangles forming a circle and to color each of these triangles with its own linear gradient. This is a definite hack and leads to larger file sizes than would be necessary if the SVG people just gave us conic gradients, but it works. You can see side-by-side three different versions, the first shows a gradient as it would normally be rendered by Typst, the second shows an example where not enough triangles were used, and the third shows an example with few outlined triangles to make them more visible. If you zoom out, you might notice that the second gradient becomes indistinguishable from the first one. This is how the illusion works and why we need so many triangles: So that the gradient looks smooth when zoomed in.

Conclusion

Implementing gradients was a far more involved endeavor than I had anticipated. It took a lot of time, in fact, close to four months of work, to get it production ready. It took a lot of trial and effort to get a solution that works smoothly across all readers. It took a lot of debugging to figure out what was wrong with the files and how to fix them. But in the end, I think it was worth it. Gradients are an essential tool for artistic and scientific endeavors and I am glad that Typst now supports them.

In this blog post, we briefly discussed the new color system, the new gradient feature, and how I painstakingly implemented them all. It goes without saying that I did not do this work alone and many of the community members on Discord also participated in many ways. I would like to thank them for their help and support throughout this process. I would also like to thank the Typst team for allowing me to publish on their official blog. Finally, I would like to thank you for reading this article and I hope you will enjoy using gradients in your documents.

Finally, I leave you with this collection of various fails and successes I encountered while implementing gradients. Enjoy this beautiful collage made in paint.

For our minimal package manager, we had the following design goals:

• Works in single-file scenarios
• Compilations are reproducible
• Supports global community packages and local system packages
• Downloads packages on-demand
• Packages work offline once downloaded

The package repository

For the package submission process, we took a big shortcut: Submitting a package means making a pull request to our package repository with the full contents of the package. A package has a name, a version and lives in a namespace. It is imported as #import "@{namespace}/{name}:{version}".

For now, all packages submitted to the shared repository live in the preview namespace. This way, we can deal with the allocation of namespaces to users and organizations later. We would not want random people claiming namespaces that should belong to universities or other institutions, but do not have infrastructure to perform validation now. The preview namespace also leaves open the option of having a non-namespaced global registry in a future iteration of the package manager.

Within the package repository, all packages are stored in folders named packages/preview/{name}-{version}. A package that has multiple version is stored there multiple times. The package repository has a GitHub action that builds a tar.gz archive for each package and an index.json with metadata about the available packages on each push. It then uploads the packages and index to https://packages.typst.org/preview, which is served through a CDN. The index is served with Cache-Control: must-revalidate because it changes frequently whereas packages are served with a max-age of 90 days because they don't change.

Package format

A package must contain a typst.toml manifest file that is heavily inspired by Cargo.toml. The three keys name, version, and entrypoint are mandated by the compiler. There are a few more metadata keys, some of which are required for submission to the shared repository and some of which are completely optional.

[package]
name = "example"
version = "0.1.0"
entrypoint = "lib.typ"

Package authors are free to structure their packages however they want. The only requirement is that the entrypoint key must point to some .typ file. Within a package, everything is encapsulated: Package code can only read files in the package and absolute paths are resolved relative to the package root.

How packages are accessed

When the command line compiler encounters a package import, it searches for the directory typst/packages/{namespace}/{name}-{version} within the OS-dependant data and cache directories.

The location in the data directory is intended for storing system-local packages while the location in the cache directory is populated through on-demand downloads of packages from the shared repository. As packages are only downloaded on use instead of upfront, Typst remains quick and easy to install.

Reproducibility is ensured through two factors:

1. We do not allow removal or change of packages after submission (an exception would require a really good reason).
2. Every import must specify the full package version. While this is a bit inconvenient, it means that we don't need a manifest or lock file for reproducibility. It is a design goal that the typst compiler works well for documents consisting of just a single .typ file and that it does not create any auxiliary files during compilation.

Crucially, because package contents do not change, a package only ever needs to be downloaded once. The CLI does not ever download the index.json and importing an already downloaded package does not result in any network access. This makes for a great offline experience.

Finding packages

A list of all community packages is available directly in the packages section of our documentation. Like the rest of the package management, this is also kept as simple as possible. It's a plain HTML page that fetches the package index client-site and displays it in a searchable table.

Each table entry links to the package's documentation in the form of a README file in package repository. It also offers a small button for copying the relevant import statement (great suggestion from our Discord). Down the road, we plan to build a documentation generator like rustdoc for Typst, but for now the documentation setup is maximally simple.

In addition to the documentation page, the package list is also available through the autocomplete panel in the web app. There are already a few packages available: The tablex package fills the current feature gaps of Typst's built-in tables while quill draws beatiful quantum circuits.

Summary

That's it! Won't get much simpler than serving a bunch of tar.gz files through a CDN and downloading them on-demand. To be clear: I'm not saying that this is the ultimate package manager. But, for Typst, it solves the immediate problem of people having to copy-paste packages into their projects in a very simple and, at least to me, elegant way.

With the package manager itself shipped, there's still one more thing we want to build around it in the near future: Designated support for template packages that show up in the web app's template gallery and support scaffolding with a CLI command.

Thanks for reading. I'd be happy to hear your thoughts! Have a good weekend and maybe submit a package?

Bibliography and references

Typst now has built-in bibliography management. You can either bring a BibTeX file or make use of Typst's native bibliography file format, Hayagriva. Add a bibliography with the bibliography function and @cite from it with the reference syntax. The same syntax can also be used to insert cross-references to sections, equations, and other things that have a <label> attached to them.

#set heading(numbering: "1.")
#set math.equation(numbering: "(1)")

= Introduction <intro>
Recent developments in
typesetting software have
rekindled hope in previously
frustrated researchers. @distress
As shown in @results, we ...

= Results <results>
We discuss our approach in
comparison with others.

== Performance <perf>
@slow demonstrates what slow
software looks like.
$ O(n) = 2^n $ <slow>

#bibliography("works.bib")

The built-in bibliography management, numbering and cross-referencing works out of the box with zero setup. But it wouldn't be in the spirit of Typst to stop there. Everything you've seen above, you can also build yourself with new low-level primitives.

Do It Yourself

With new counter function, you can inspect and modify the counters of pages, headings, figures, and create custom ones. Maybe your document contains a bunch of theorems that you want to count through? The counter function ensures that the theorems are numbered exactly in the order of the final layout, no matter how you organize them in the markup.

#let c = counter("theorem")
#let theorem(body) = [
  #set par(hanging-indent: 10pt)
  *Theorem #context c.display().*
  #body
  #c.step()
]

#theorem[
  The square of any real number is
  non-negative.
]

#theorem[
  The sum $1 + ... + n$ is:
  $ sum_(k=1)^n k = (n(n+1))/2 $
]

Aside from counters, you might want to manage other state across your document. The new state has got you covered.

A particularly cool addition is the query function. This function lets search for elements in your document. You can use it to build a custom list of figures or to create a page header that displays the current chapter title.

The example below demonstrates what queries can do: We first call the locate function to determine the location of itself within the document. We then query for all headings after that location. The result is an array with all matching elements. Since the "Introduction" heading is before the locate call and we queried for headings after the location, this prints "Upcoming: Background and Analysis."

= Introduction
#context {
  let upcoming = query(
    selector(heading).after(here()),
  )
  [Upcoming: ]
  upcoming
    .map(it => it.body)
    .join[ and ]
}.

= Background
#lorem(10)

= Analysis
#lorem(10)

The new measure function lets you find out the layouted size of some content. That's super useful for building flexible layouts that react to what's given to them.

#style(styles => {
  let content = [Hello]
  let size = measure(content, styles)
  [#content has width #size.width]
})

If you've previously dealt with content values in Typst, you might be familiar with these four letters: [..]. Previously, content was really opaque in Typst and you couldn't really do much it with except put it somewhere in your layout. This ends today. With the new update, you can have a look at what's inside of content values, compare them, and traverse them with code.

People have already built some cool libraries in Typst during the preview test. But they have been limited by the lack of lower level primitives for state handling and content manipulation. We hope that the additions in today's update make it easier to create packages and abstractions from which the whole community can benefit.

Web App Improvements

We've not only been busy with the Typst language and compiler. The web has also gotten some long-awaited upgrades.

The new jump-to-source feature lets you click on anything in the preview panel and brings you straight to the exact piece of source code that produced it. It works for text, images, shapes, and even inside of equations!

Alongside the template creator, the web app now has a template gallery. It ships with five pre-made templates that you can use for your documents. That's just the start though: More templates will be added over time and we also plan to integrate the gallery with the upcoming package manager.

When editing a document, it's often the small things that matter: We've added a few new editor buttons to the app, so that you can insert headings, equations, code blocks and references more easily. Furthermore, we've improved the hover tooltips so that they work properly for multi-file setups and in show rules.

The Typst app ships with a selection of fonts that cover a wide range of use cases. But something you just want that one particular font. You can now upload your own fonts into the web app. There's even a little preview if you click on them in the file panel.

That's it for this update! Visit the changelog for a comprehensive overview of all changes. And if you like where Typst is going, be sure to share it with your friends and colleagues!

Typst is now open-source

To make Typst accessible and true to an open science / open access mindset, we are open sourcing the Typst compiler on GitHub. The compiler is the foundation on which we built our web app. We have worked on it for almost four years, with relentless focus on detail and are proud to share it with you now. With the compiler out in the open, everyone can contribute to the features of the Typst platform by opening issues or collaborating on the code and documentation. An open compiler also ensures that you will always be able to compile your Typst documents. No lock-in, ever!

Bibliography, templates, and more

Alongside our beta launch, we're shipping a big update today. It contains enough new features and improvements to get its own blog post, but let's zero in on a few of the highlights: Typst can now automatically manage your bibliography. Just upload your existing bibtex file and start by @citing your literature. Typst will display the appropriate in-text citation and prepare a bibliography for you.

Typst already has had an interactive template creator for new documents, but today we are adding five pre-made templates to the new template gallery. IEEE and AMS papers accurately replicate the look of the IEEEproc and AMSart LaTeX document classes and the department newsletter is a fun and colorful way to share what's new in your organization.

When working with markup, you frequently jump between preview and source. We make this easy: You can click in the preview and your markup cursor will be placed at the exact corresponding location! Typst also automatically scrolls the preview to the right spot when you're writing in the source code.

Finally, we are adding more scripting features today that allow you to count elements, work with state, and find elements within your Typst documents. These features will be great for package and template creators. (Stay tuned for our package manager!)

Looking back and forward

None of this would have been possible without the testers in our closed preview. They helped us find bugs we would have never thought of, test-drive Typst in real-world conditions, and prioritize our roadmap. A tid-bit from a survey we ran with them: Most people got productive in Typst in an hour or less, so Typst really is accessible and easy to learn! We also shipped a comprehensive maths mode during the preview test. and people seem to love it.

Together with the Preview members, we built a great Discord server where we hang out as a community. I'd like to invite all of you to join, too: It's the best place to get your questions answered and nerd out about typography and scripting.

Get started and help us spread the word

If any of that made you curious, create a Typst account, check out the tutorial, and get writing! If you like what you saw there, please help us out by sharing Typst with your friends, colleagues, and the wider science- and nerdosphere: Message friends your referral link, share the Product Hunt launch, discuss our open-sourcing on Hacker News, or go on your favorite subreddit! Thanks to everyone who's helping us to bring scientific writing to the next level!

But there is one thing we have heard time and again: To be used for research and university, Typst needs proper math typesetting. While the existing math mode demonstrated how we imagined math to work in Typst, it was very limiting and broken in myriad ways. Today, we deliver on the original promise of Typst's math mode: We are releasing a large update with a completely rebuilt math mode, lots of new features and tons of bugfixes. Apart from math, this update also contains improvements to the collaboration & editing experience in our web app. Let's get into it!

Hash Syntax

First of all, an important breaking change to Typst's syntax: The hash syntax in markup has been expanded to support more expressions (including field accesses, method calls, strings, parenthesized expressions, and blocks). At the same time, code and content blocks now require a leading hash. Curly braces and balanced square brackets directly in markup are now displayed verbatim. This change makes code even more comfortable to embed into markup and brings more consistency between expressions in markup and math. As a further improvements, we changed the import syntax so that the path comes before the import items, enabling autocompletion for the items. For more details on these changes, see the updated scripting page.

#false \
#emoji.face \
#"string".len() \
#(1 + 2) \
#{ let x = 3; x + 4 }

New Math Mode

With this out of the way, let's get to the math mode! Previously, Typst's math mode used ReX internally, a library that replicates TeX's math layout in Rust. As of today, we no longer depend on ReX. Instead, we have implemented our own, fully custom math typesetting. This new engine brings many improvements, including better symbol support, text operators, smart delimiter matching, multi-line alignment and matrices. Furthermore, mathematical formulas can now use all of Typst's regular functions and contain all kinds of content (e.g., images).

Symbols

With this update, we removed the special symbol syntax. Rather than having custom and hard-to-extend syntax, symbols are now normal values. Typst defines many useful symbols in the sym and emoji modules, but you can also define your own with the symbol function. The linked documentation pages also feature our new symbol picker.

#sym.arrow.r \
#emoji.face.halo \
$alpha^2 lt.eq.not Delta$

The new symbol system retains the concept of symbol modifiers, but they are now applied using the field access syntax, as in arrow.r.long. This shrinks the syntax surface and is less visually noisy than the colon that was used before. Another improvement we made is with accent symbols. To attach them to a base, you can now call them like functions instead of using the accent function.

$tilde(n)$
$arrow(A)$
$accent(A, ->)$
$accent(A, arrow)$

Text Operators

Typst now predefines well-known operators like lim and sin. Arbitrary text operators can be created with the op function. This function ensures correct spacing and control over placement of scripts/limits.

$ tan(x) = (sin x)/(cos x) $
$ lim_(n->oo) 1/n $

Delimiter matching

Delimiter usage in math is tricky. Typically, pairs of mirrored delimiters are used, but it's also common to pair different brackets (e.g. $[a, b)$) or non-mirrored brackets (e.g. $]a,b]$). Typst's new math mode automatically matches and scales pairs of opening and closing delimiters, but also allows you to (1) prevent scaling by escaping the brackets, and (2) manually match two arbitrary brackets with the lr function. This function also allows you to take exact control over the delimiter sizes: This comes in handy for instance when typesetting sums, where automatically scaled brackets might be overly large.

$ (a/2 + b) = |x/2| $
$ lr(]a/2]) $
$ lr((sum_a^b), size: #70%) $

Multi-line alignment

Math mode now supports multi-line math with alignment points. Insert a line break with the backslash (\) and an alignment point with the ampersand (&). You can also use multiple alignment points within each line to align at multiple positions.

$ sum_(x=0)^n
    &= 1 + ... + n \
    &= (n(n+1)) / 2 $

Matrices

We've now also added matrices in addition to vectors. As these are 2-dimensional in nature, some indicator is needed to separate rows. For this, Typst's math mode gained the new semicolon syntax that turns the preceding arguments into an array. The matrix function itself is blissfully unaware of this, it simply takes an arbitrary number of arrays as arguments. This also makes it easy to create matrices entirely from code!

$ mat(
  1, 2, ..., 10;
  2, 2, ..., 10;
  dots.v, dots.v, dots.down, dots.v;
  10, 10, ..., 10;
) $

#let data = ((1, 2, 3), (4, 5, 6))
#let matrix = math.mat(..data)
$ v := matrix $

And More ...

Typst's new math mode has many other new features, including:

• Non-square roots
• Under- and overbraces, -brackets, and -lines
• Control over whether attachments display as sub/superscripts or limits
• Manual spacing with h and predefined thin, med, thick, and quad spacings
• Support for different text colors
• Support for alternative math fonts through:
  #show math.formula: set text("Fira Math")

Also, there's this other kind of math you might wanna do. Where you really calculate things. Typst's new calc module equips you with the functions needed to do that.

Editing

But math isn't all we've been working on. We have also developed something really cool: Tooltips now let you peek into your code. If you hover over a variable name in your Typst source code, you can see all the values it ever takes on! Similarly, hovering over a for-loop shows a tooltip with the loop's value. This comes in handy when you use Typst's scripting capabilities and takes debugging your automations to the next level. Forget print debugging. Just hover over your values and see what's going on.

We also made autocomplete smarter: It now completes local variables and is aware of their values and types. The autocomplete panel shows dictionary keys, module definitions, and methods on values. Furthermore, it helps you select the right symbol by offering all available modifiers for a symbol after you entered a dot behind the symbol name.

Ever wondered what fonts you can use with Typst? We've added a font picker with previews to the editor. Just press the button to check out the list of available fonts. Note that we are not displaying all global variants of the Noto and IBM Plex fonts to keep things concise, but they of course remain accessible with the text function.

Cloud

Last but not least, there are a couple of new features and improvements we have already rolled out int the past weeks.

Link sharing offers new opportunities for collaboration on single documents: Need to write a group report for class? Do you want a colleague to review your paper? You can use the share button in the editor to create share links that you can distribute to grant access to your project. At the moment, the receivers of the share link also need a Typst account, but we will add anonymous access in the future. In the meantime, you can find collaborators in our Discord community, or, if you do not have access yet, be sure to sign up for the wait list and join our Discord anyway!

We have also improved the reliability of all of Typst's components. Be it unusual or fast input or bad internet connections, Typst should now be able to deal with it better. To improve the user experience, Typst further gained more keyboard shortcuts (with indicators in the menus) and descriptive tooltips on all icon buttons.

That's it for the first update after the infrastructure test started. What's your favorite feature in this release? Is something you need still missing? We'd love to hear from you on the Discord or by tweeting at @typstapp. For a comprehensive overview over the changes in this update, also see the changelog.