+```
+
+
+
+So far, we've passed content blocks (markup in square brackets) and strings
+(text in double quotes) to our functions. Both seem to contain text. What's the
+difference?
+
+A content block can contain text, but also any other kind of markup, function
+calls, and more, whereas a string is really just a _sequence of characters_ and
+nothing else.
+
+For example, the image function expects a path to an image file.
+It would not make sense to pass, e.g., a paragraph of text or another image as
+the image's path parameter. That's why only strings are allowed here.
+In contrast, strings work wherever content is expected because text is a
+valid kind of content.
+
+
+## Adding a bibliography { #bibliography }
+As you write up your report, you need to back up some of your claims. You can
+add a bibliography to your document with the [`bibliography`] function. This
+function expects a path to a bibliography file.
+
+Typst's native bibliography format is
+[Hayagriva](https://github.com/typst/hayagriva/blob/main/docs/file-format.md),
+but for compatibility you can also use BibLaTeX files. As your classmate has
+already done a literature survey and sent you a `.bib` file, you'll use that
+one. Upload the file through the file panel to access it in Typst.
+
+Once the document contains a bibliography, you can start citing from it.
+Citations use the same syntax as references to a label. As soon as you cite a
+source for the first time, it will appear in the bibliography section of your
+document. Typst supports different citation and bibliography styles. Consult the
+[reference]($bibliography.style) for more details.
+
+```example
+= Methods
+We follow the glacier melting models
+established in @glacier-melt.
+
+#bibliography("works.bib")
+```
+
+## Maths
+After fleshing out the methods section, you move on to the meat of the document:
+Your equations. Typst has built-in mathematical typesetting and uses its own
+math notation. Let's start with a simple equation. We wrap it in `[$]` signs
+to let Typst know it should expect a mathematical expression:
+
+```example
+The equation $Q = rho A v + C$
+defines the glacial flow rate.
+```
+
+The equation is typeset inline, on the same line as the surrounding text. If you
+want to have it on its own line instead, you should insert a single space at its
+start and end:
+
+```example
+The flow rate of a glacier is
+defined by the following equation:
+
+$ Q = rho A v + C $
+```
+
+We can see that Typst displayed the single letters `Q`, `A`, `v`, and `C` as-is,
+while it translated `rho` into a Greek letter. Math mode will always show single
+letters verbatim. Multiple letters, however, are interpreted as symbols,
+variables, or function names. To imply a multiplication between single letters,
+put spaces between them.
+
+If you want to have a variable that consists of multiple letters, you can
+enclose it in quotes:
+
+```example
+The flow rate of a glacier is given
+by the following equation:
+
+$ Q = rho A v + "time offset" $
+```
+
+You'll also need a sum formula in your paper. We can use the `sum` symbol and
+then specify the range of the summation in sub- and superscripts:
+
+```example
+Total displaced soil by glacial flow:
+
+$ 7.32 beta +
+ sum_(i=0)^nabla Q_i / 2 $
+```
+
+To add a subscript to a symbol or variable, type a `_` character and then the
+subscript. Similarly, use the `^` character for a superscript. If your
+sub- or superscript consists of multiple things, you must enclose them
+in round parentheses.
+
+The above example also showed us how to insert fractions: Simply put a `/`
+character between the numerator and the denominator and Typst will automatically
+turn it into a fraction. Parentheses are smartly resolved, so you can enter your
+expression as you would into a calculator and Typst will replace parenthesized
+sub-expressions with the appropriate notation.
+
+```example
+Total displaced soil by glacial flow:
+
+$ 7.32 beta +
+ sum_(i=0)^nabla
+ (Q_i (a_i - epsilon)) / 2 $
+```
+
+Not all math constructs have special syntax. Instead, we use functions, just
+like the `image` function we have seen before. For example, to insert a column
+vector, we can use the [`vec`]($math.vec) function. Within math mode, function
+calls don't need to start with the `#` character.
+
+```example
+$ v := vec(x_1, x_2, x_3) $
+```
+
+Some functions are only available within math mode. For example, the
+[`cal`]($math.cal) function is used to typeset calligraphic letters commonly
+used for sets. The [math section of the reference]($category/math) provides a
+complete list of all functions that math mode makes available.
+
+One more thing: Many symbols, such as the arrow, have a lot of variants. You can
+select among these variants by appending a dot and a modifier name to a symbol's
+name:
+
+```example
+$ a arrow.squiggly b $
+```
+
+This notation is also available in markup mode, but the symbol name must be
+preceded with `#sym.` there. See the [symbols section]($category/symbols/sym)
+for a list of all available symbols.
+
+## Review
+You have now seen how to write a basic document in Typst. You learned how to
+emphasize text, write lists, insert images, align content, and typeset
+mathematical expressions. You also learned about Typst's functions. There are
+many more kinds of content that Typst lets you insert into your document, such
+as [tables]($table), [shapes]($category/visualize), and [code blocks]($raw). You
+can peruse the [reference] to learn more about these and other features.
+
+For the moment, you have completed writing your report. You have already saved a
+PDF by clicking on the download button in the top right corner. However, you
+think the report could look a bit less plain. In the next section, we'll learn
+how to customize the look of our document.
diff --git a/sources/docs/tutorial/2-formatting.md b/sources/docs/tutorial/2-formatting.md
new file mode 100644
index 0000000000000000000000000000000000000000..a8c72cefe02ed1d01d320fb7a6a61651c702f3c6
--- /dev/null
+++ b/sources/docs/tutorial/2-formatting.md
@@ -0,0 +1,280 @@
+---
+description: Typst's tutorial.
+---
+
+# Formatting
+So far, you have written a report with some text, a few equations and images.
+However, it still looks very plain. Your teaching assistant does not yet know
+that you are using a new typesetting system, and you want your report to fit in
+with the other student's submissions. In this chapter, we will see how to format
+your report using Typst's styling system.
+
+## Set rules
+As we have seen in the previous chapter, Typst has functions that _insert_
+content (e.g. the [`image`] function) and others that _manipulate_ content that
+they received as arguments (e.g. the [`align`] function). The first impulse you
+might have when you want, for example, to change the font, could be to look
+for a function that does that and wrap the complete document in it.
+
+```example
+#text(font: "New Computer Modern")[
+ = Background
+ In the case of glaciers, fluid
+ dynamics principles can be used
+ to understand how the movement
+ and behaviour of the ice is
+ influenced by factors such as
+ temperature, pressure, and the
+ presence of other fluids (such as
+ water).
+]
+```
+
+Wait, shouldn't all arguments of a function be specified within parentheses? Why
+is there a second set of square brackets with content _after_ the parentheses?
+The answer is that, as passing content to a function is such a common thing to
+do in Typst, there is special syntax for it: Instead of putting the content
+inside of the argument list, you can write it in square brackets directly after
+the normal arguments, saving on punctuation.
+
+As seen above, that works. With the [`text`] function, we can adjust the font
+for all text within it. However, wrapping the document in countless functions
+and applying styles selectively and in-situ can quickly become cumbersome.
+
+Fortunately, Typst has a more elegant solution. With _set rules,_ you can apply
+style properties to all occurrences of some kind of content. You write a set
+rule by entering the `{set}` keyword, followed by the name of the function whose
+properties you want to set, and a list of arguments in parentheses.
+
+```example
+#set text(
+ font: "New Computer Modern"
+)
+
+= Background
+In the case of glaciers, fluid
+dynamics principles can be used
+to understand how the movement
+and behaviour of the ice is
+influenced by factors such as
+temperature, pressure, and the
+presence of other fluids (such as
+water).
+```
+
+
+
+Want to know in more technical terms what is happening here?
+
+Set rules can be conceptualized as setting default values
+for some of the parameters of a function for all future
+uses of that function.
+
+
+## The autocomplete panel { #autocomplete }
+If you followed along and tried a few things in the app, you might have noticed
+that always after you enter a `#` character, a panel pops up to show you the
+available functions, and, within an argument list, the available parameters.
+That's the autocomplete panel. It can be very useful while you are writing your
+document: You can apply its suggestions by hitting the Return key or navigate to
+the desired completion with the arrow keys. The panel can be dismissed by
+hitting the Escape key and opened again by typing `#` or hitting
+Ctrl + Space. Use the autocomplete panel to discover the
+right arguments for functions. Most suggestions come with a small description of
+what they do.
+
+
+
+## Set up the page { #page-setup }
+Back to set rules: When writing a rule, you choose the function depending on
+what type of element you want to style. Here is a list of some functions that
+are commonly used in set rules:
+
+- [`text`] to set font family, size, color, and other properties of text
+- [`page`] to set the page size, margins, headers, enable columns, and footers
+- [`par`] to justify paragraphs, set line spacing, and more
+- [`heading`] to set the appearance of headings and enable numbering
+- [`document`] to set the metadata contained in the PDF output, such as title
+ and author
+
+Not all function parameters can be set. In general, only parameters that tell
+a function _how_ to do something can be set, not those that tell it _what_ to
+do it with. The function reference pages indicate which parameters are settable.
+
+Let's add a few more styles to our document. We want larger margins and a serif
+font. For the purposes of the example, we'll also set another page size.
+
+```example
+#set page(
+ paper: "a6",
+ margin: (x: 1.8cm, y: 1.5cm),
+)
+#set text(
+ font: "New Computer Modern",
+ size: 10pt
+)
+#set par(
+ justify: true,
+ leading: 0.52em,
+)
+
+= Introduction
+In this report, we will explore the
+various factors that influence fluid
+dynamics in glaciers and how they
+contribute to the formation and
+behaviour of these natural structures.
+
+>>> Glacier displacement is influenced
+>>> by a number of factors, including
+>>> + The climate
+>>> + The topography
+>>> + The geology
+>>>
+>>> This report will present a physical
+>>> model of glacier displacement and
+>>> dynamics, and will explore the
+>>> influence of these factors on the
+>>> movement of large bodies of ice.
+<<< ...
+
+#align(center + bottom)[
+ #image("glacier.jpg", width: 70%)
+
+ *Glaciers form an important
+ part of the earth's climate
+ system.*
+]
+```
+
+There are a few things of note here.
+
+First is the [`page`] set rule. It receives two arguments: the page size and
+margins for the page. The page size is a string. Typst accepts [many standard
+page sizes,]($page.paper) but you can also specify a custom page size. The
+margins are specified as a [dictionary.]($dictionary) Dictionaries are a
+collection of key-value pairs. In this case, the keys are `x` and `y`, and the
+values are the horizontal and vertical margins, respectively. We could also have
+specified separate margins for each side by passing a dictionary with the keys
+`{left}`, `{right}`, `{top}`, and `{bottom}`.
+
+Next is the set [`text`] set rule. Here, we set the font size to `{10pt}` and
+font family to `{"New Computer Modern"}`. The Typst app comes with many fonts
+that you can try for your document. When you are in the text function's argument
+list, you can discover the available fonts in the autocomplete panel.
+
+We have also set the spacing between lines (a.k.a. leading): It is specified as
+a [length] value, and we used the `em` unit to specify the leading relative to
+the size of the font: `{1em}` is equivalent to the current font size (which
+defaults to `{11pt}`).
+
+Finally, we have bottom aligned our image by adding a vertical alignment to our
+center alignment. Vertical and horizontal alignments can be combined with the
+`{+}` operator to yield a 2D alignment.
+
+## A hint of sophistication { #sophistication }
+To structure our document more clearly, we now want to number our headings. We
+can do this by setting the `numbering` parameter of the [`heading`] function.
+
+```example
+>>> #set text(font: "New Computer Modern")
+#set heading(numbering: "1.")
+
+= Introduction
+#lorem(10)
+
+== Background
+#lorem(12)
+
+== Methods
+#lorem(15)
+```
+
+We specified the string `{"1."}` as the numbering parameter. This tells Typst to
+number the headings with arabic numerals and to put a dot between the number of
+each level. We can also use [letters, roman numerals, and symbols]($numbering)
+for our headings:
+
+```example
+>>> #set text(font: "New Computer Modern")
+#set heading(numbering: "1.a")
+
+= Introduction
+#lorem(10)
+
+== Background
+#lorem(12)
+
+== Methods
+#lorem(15)
+```
+
+This example also uses the [`lorem`] function to generate some placeholder text.
+This function takes a number as an argument and generates that many words of
+_Lorem Ipsum_ text.
+
+
+
+Did you wonder why the headings and text set rules apply to all text and headings,
+even if they are not produced with the respective functions?
+
+Typst internally calls the `heading` function every time you write
+`[= Conclusion]`. In fact, the function call `[#heading[Conclusion]]` is
+equivalent to the heading markup above. Other markup elements work similarly,
+they are only _syntax sugar_ for the corresponding function calls.
+
+
+## Show rules
+You are already pretty happy with how this turned out. But one last thing needs
+to be fixed: The report you are writing is intended for a larger project and
+that project's name should always be accompanied by a logo, even in prose.
+
+You consider your options. You could add an `[#image("logo.svg")]` call before
+every instance of the logo using search and replace. That sounds very tedious.
+Instead, you could maybe
+[define a custom function]($function/#defining-functions) that always yields the
+logo with its image. However, there is an even easier way:
+
+With show rules, you can redefine how Typst displays certain elements. You
+specify which elements Typst should show differently and how they should look.
+Show rules can be applied to instances of text, many functions, and even the
+whole document.
+
+```example
+#show "ArtosFlow": name => box[
+ #box(image(
+ "logo.svg",
+ height: 0.7em,
+ ))
+ #name
+]
+
+This report is embedded in the
+ArtosFlow project. ArtosFlow is a
+project of the Artos Institute.
+```
+
+There is a lot of new syntax in this example: We write the `{show}` keyword,
+followed by a string of text we want to show differently and a colon. Then, we
+write a function that takes the content that shall be shown as an argument.
+Here, we called that argument `name`. We can now use the `name` variable in the
+function's body to print the ArtosFlow name. Our show rule adds the logo image
+in front of the name and puts the result into a box to prevent linebreaks from
+occurring between logo and name. The image is also put inside of a box, so that
+it does not appear in its own paragraph.
+
+The calls to the first box function and the image function did not require a
+leading `#` because they were not embedded directly in markup. When Typst
+expects code instead of markup, the leading `#` is not needed to access
+functions, keywords, and variables. This can be observed in parameter lists,
+function definitions, and [code blocks]($scripting).
+
+## Review
+You now know how to apply basic formatting to your Typst documents. You learned
+how to set the font, justify your paragraphs, change the page dimensions, and
+add numbering to your headings with set rules. You also learned how to use a
+basic show rule to change how text appears throughout your document.
+
+You have handed in your report. Your supervisor was so happy with it that they
+want to adapt it into a conference paper! In the next section, we will learn how
+to format your document as a paper using more advanced show rules and functions.
diff --git a/sources/docs/tutorial/3-advanced.md b/sources/docs/tutorial/3-advanced.md
new file mode 100644
index 0000000000000000000000000000000000000000..b7f338db589a2fcaeb8f18047568f6798ad014c4
--- /dev/null
+++ b/sources/docs/tutorial/3-advanced.md
@@ -0,0 +1,546 @@
+---
+description: Typst's tutorial.
+---
+
+# Advanced Styling
+In the previous two chapters of this tutorial, you have learned how to write a
+document in Typst and how to change its formatting. The report you wrote
+throughout the last two chapters got a straight A and your supervisor wants to
+base a conference paper on it! The report will of course have to comply with the
+conference's style guide. Let's see how we can achieve that.
+
+Before we start, let's create a team, invite your supervisor and add them to the
+team. You can do this by going back to the app dashboard with the back icon in
+the top left corner of the editor. Then, choose the plus icon in the left
+toolbar and create a team. Finally, click on the new team and go to its settings
+by clicking 'manage team' next to the team name. Now you can invite your
+supervisor by email.
+
+
+
+Next, move your project into the team: Open it, going to its settings by
+choosing the gear icon in the left toolbar and selecting your new team from the
+owners dropdown. Don't forget to save your changes!
+
+Now, your supervisor can also edit the project and you can both see the changes
+in real time. You can join our [Discord server](https://discord.gg/2uDybryKPe)
+to find other users and try teams with them!
+
+## The conference guidelines { #guidelines }
+The layout guidelines are available on the conference website. Let's take a look
+at them:
+
+- The font should be an 11pt serif font
+- The title should be in 17pt and bold
+- The paper contains a single-column abstract and two-column main text
+- The abstract should be centered
+- The main text should be justified
+- First level section headings should be 13pt, centered, and rendered in small
+ capitals
+- Second level headings are run-ins, italicized and have the same size as the
+ body text
+- Finally, the pages should be US letter sized, numbered in the center of the
+ footer and the top right corner of each page should contain the title of the
+ paper
+
+We already know how to do many of these things, but for some of them, we'll need
+to learn some new tricks.
+
+## Writing the right set rules { #set-rules }
+Let's start by writing some set rules for the document.
+
+```example
+#set page(
+>>> margin: auto,
+ paper: "us-letter",
+ header: align(right)[
+ A fluid dynamic model for
+ glacier flow
+ ],
+ numbering: "1",
+)
+#set par(justify: true)
+#set text(
+ font: "Libertinus Serif",
+ size: 11pt,
+)
+
+#lorem(600)
+```
+
+You are already familiar with most of what is going on here. We set the text
+size to `{11pt}` and the font to Libertinus Serif. We also enable paragraph
+justification and set the page size to US letter.
+
+The `header` argument is new: With it, we can provide content to fill the top
+margin of every page. In the header, we specify our paper's title as requested
+by the conference style guide. We use the `align` function to align the text to
+the right.
+
+Last but not least is the `numbering` argument. Here, we can provide a
+[numbering pattern]($numbering) that defines how to number the pages. By
+setting into to `{"1"}`, Typst only displays the bare page number. Setting it to
+`{"(1/1)"}` would have displayed the current page and total number of pages
+surrounded by parentheses. And we could even have provided a completely custom
+function here to format things to our liking.
+
+## Creating a title and abstract { #title-and-abstract }
+Now, let's add a title and an abstract. We'll start with the title. We center
+align it and increase its font weight by enclosing it in `[*stars*]`.
+
+```example
+>>> #set page(width: 300pt, margin: 30pt)
+>>> #set text(font: "Libertinus Serif", 11pt)
+#align(center, text(17pt)[
+ *A fluid dynamic model
+ for glacier flow*
+])
+```
+
+This looks right. We used the `text` function to override the previous text
+set rule locally, increasing the size to 17pt for the function's argument. Let's
+also add the author list: Since we are writing this paper together with our
+supervisor, we'll add our own and their name.
+
+```example
+>>> #set page(width: 300pt, margin: 30pt)
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>>
+>>> #align(center, text(17pt)[
+>>> *A fluid dynamic model
+>>> for glacier flow*
+>>> ])
+#grid(
+ columns: (1fr, 1fr),
+ align(center)[
+ Therese Tungsten \
+ Artos Institute \
+ #link("mailto:tung@artos.edu")
+ ],
+ align(center)[
+ Dr. John Doe \
+ Artos Institute \
+ #link("mailto:doe@artos.edu")
+ ]
+)
+```
+
+The two author blocks are laid out next to each other. We use the [`grid`]
+function to create this layout. With a grid, we can control exactly how large
+each column is and which content goes into which cell. The `columns` argument
+takes an array of [relative lengths]($relative) or [fractions]($fraction). In
+this case, we passed it two equal fractional sizes, telling it to split the
+available space into two equal columns. We then passed two content arguments to
+the grid function. The first with our own details, and the second with our
+supervisors'. We again use the `align` function to center the content within the
+column. The grid takes an arbitrary number of content arguments specifying the
+cells. Rows are added automatically, but they can also be manually sized with
+the `rows` argument.
+
+Now, let's add the abstract. Remember that the conference wants the abstract to
+be set ragged and centered.
+
+```example:0,0,612,317.5
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>> #set par(justify: true)
+>>> #set page(
+>>> "us-letter",
+>>> margin: auto,
+>>> header: align(right + horizon)[
+>>> A fluid dynamic model for
+>>> glacier flow
+>>> ],
+>>> numbering: "1",
+>>> )
+>>>
+>>> #align(center, text(17pt)[
+>>> *A fluid dynamic model
+>>> for glacier flow*
+>>> ])
+>>>
+>>> #grid(
+>>> columns: (1fr, 1fr),
+>>> align(center)[
+>>> Therese Tungsten \
+>>> Artos Institute \
+>>> #link("mailto:tung@artos.edu")
+>>> ],
+>>> align(center)[
+>>> Dr. John Doe \
+>>> Artos Institute \
+>>> #link("mailto:doe@artos.edu")
+>>> ]
+>>> )
+>>>
+<<< ...
+
+#align(center)[
+ #set par(justify: false)
+ *Abstract* \
+ #lorem(80)
+]
+>>> #lorem(600)
+```
+
+Well done! One notable thing is that we used a set rule within the content
+argument of `align` to turn off justification for the abstract. This does not
+affect the remainder of the document even though it was specified after the
+first set rule because content blocks _scope_ styling. Anything set within a
+content block will only affect the content within that block.
+
+Another tweak could be to save the paper title in a variable, so that we do not
+have to type it twice, for header and title. We can do that with the `{let}`
+keyword:
+
+```example:single
+#let title = [
+ A fluid dynamic model
+ for glacier flow
+]
+
+<<< ...
+
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>> #set par(justify: true)
+#set page(
+>>> "us-letter",
+>>> margin: auto,
+ header: align(
+ right + horizon,
+ title
+ ),
+<<< ...
+>>> numbering: "1",
+)
+
+#align(center, text(17pt)[
+ *#title*
+])
+
+<<< ...
+
+>>> #grid(
+>>> columns: (1fr, 1fr),
+>>> align(center)[
+>>> Therese Tungsten \
+>>> Artos Institute \
+>>> #link("mailto:tung@artos.edu")
+>>> ],
+>>> align(center)[
+>>> Dr. John Doe \
+>>> Artos Institute \
+>>> #link("mailto:doe@artos.edu")
+>>> ]
+>>> )
+>>>
+>>> #align(center)[
+>>> #set par(justify: false)
+>>> *Abstract* \
+>>> #lorem(80)
+>>> ]
+>>>
+>>> #lorem(600)
+```
+
+After we bound the content to the `title` variable, we can use it in functions
+and also within markup (prefixed by `#`, like functions). This way, if we decide
+on another title, we can easily change it in one place.
+
+## Adding columns and headings { #columns-and-headings }
+The paper above unfortunately looks like a wall of lead. To fix that, let's add
+some headings and switch our paper to a two-column layout. Fortunately, that's
+easy to do: We just need to amend our `page` set rule with the `columns`
+argument.
+
+By adding `{columns: 2}` to the argument list, we have wrapped the whole
+document in two columns. However, that would also affect the title and authors
+overview. To keep them spanning the whole page, we can wrap them in a function
+call to [`{place}`]($place). Place expects an alignment and the content it
+should place as positional arguments. Using the named `{scope}` argument, we can
+decide if the items should be placed relative to the current column or its
+parent (the page). There is one more thing to configure: If no other arguments
+are provided, `{place}` takes its content out of the flow of the document and
+positions it over the other content without affecting the layout of other
+content in its container:
+
+```example
+#place(
+ top + center,
+ rect(fill: black),
+)
+#lorem(30)
+```
+
+If we hadn't used `{place}` here, the square would be in its own line, but here
+it overlaps the few lines of text following it. Likewise, that text acts like as
+if there was no square. To change this behavior, we can pass the argument
+`{float: true}` to ensure that the space taken up by the placed item at the top
+or bottom of the page is not occupied by any other content.
+
+```example:single
+>>> #let title = [
+>>> A fluid dynamic model
+>>> for glacier flow
+>>> ]
+>>>
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>> #set par(justify: true)
+>>>
+#set page(
+>>> margin: auto,
+ paper: "us-letter",
+ header: align(
+ right + horizon,
+ title
+ ),
+ numbering: "1",
+ columns: 2,
+)
+
+#place(
+ top + center,
+ float: true,
+ scope: "parent",
+ clearance: 2em,
+)[
+>>> #text(
+>>> 17pt,
+>>> weight: "bold",
+>>> title,
+>>> )
+>>>
+>>> #grid(
+>>> columns: (1fr, 1fr),
+>>> [
+>>> Therese Tungsten \
+>>> Artos Institute \
+>>> #link("mailto:tung@artos.edu")
+>>> ],
+>>> [
+>>> Dr. John Doe \
+>>> Artos Institute \
+>>> #link("mailto:doe@artos.edu")
+>>> ]
+>>> )
+<<< ...
+
+ #par(justify: false)[
+ *Abstract* \
+ #lorem(80)
+ ]
+]
+
+= Introduction
+#lorem(300)
+
+= Related Work
+#lorem(200)
+```
+
+In this example, we also used the `clearance` argument of the `{place}` function
+to provide the space between it and the body instead of using the [`{v}`]($v)
+function. We can also remove the explicit `{align(center, ..)}` calls around the
+various parts since they inherit the center alignment from the placement.
+
+Now there is only one thing left to do: Style our headings. We need to make them
+centered and use small capitals. Because the `heading` function does not offer
+a way to set any of that, we need to write our own heading show rule.
+
+```example:50,250,265,270
+>>> #let title = [
+>>> A fluid dynamic model
+>>> for glacier flow
+>>> ]
+>>>
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>> #set par(justify: true)
+>>> #set page(
+>>> "us-letter",
+>>> margin: auto,
+>>> header: align(
+>>> right + horizon,
+>>> title
+>>> ),
+>>> numbering: "1",
+>>> columns: 2,
+>>> )
+#show heading: it => [
+ #set align(center)
+ #set text(13pt, weight: "regular")
+ #block(smallcaps(it.body))
+]
+
+<<< ...
+>>>
+>>> #place(
+>>> top + center,
+>>> float: true,
+>>> scope: "parent",
+>>> clearance: 2em,
+>>> )[
+>>> #text(
+>>> 17pt,
+>>> weight: "bold",
+>>> title,
+>>> )
+>>>
+>>> #grid(
+>>> columns: (1fr, 1fr),
+>>> [
+>>> Therese Tungsten \
+>>> Artos Institute \
+>>> #link("mailto:tung@artos.edu")
+>>> ],
+>>> [
+>>> Dr. John Doe \
+>>> Artos Institute \
+>>> #link("mailto:doe@artos.edu")
+>>> ]
+>>> )
+>>>
+>>> #par(justify: false)[
+>>> *Abstract* \
+>>> #lorem(80)
+>>> ]
+>>> ]
+>>>
+>>> = Introduction
+>>> #lorem(35)
+>>>
+>>> == Motivation
+>>> #lorem(45)
+```
+
+This looks great! We used a show rule that applies to all headings. We give it a
+function that gets passed the heading as a parameter. That parameter can be used
+as content but it also has some fields like `title`, `numbers`, and `level` from
+which we can compose a custom look. Here, we are center-aligning, setting the
+font weight to `{"regular"}` because headings are bold by default, and use the
+[`smallcaps`] function to render the heading's title in small capitals.
+
+The only remaining problem is that all headings look the same now. The
+"Motivation" and "Problem Statement" subsections ought to be italic run in
+headers, but right now, they look indistinguishable from the section headings. We
+can fix that by using a `where` selector on our set rule: This is a
+[method]($scripting/#methods) we can call on headings (and other
+elements) that allows us to filter them by their level. We can use it to
+differentiate between section and subsection headings:
+
+```example:50,250,265,245
+>>> #let title = [
+>>> A fluid dynamic model
+>>> for glacier flow
+>>> ]
+>>>
+>>> #set text(font: "Libertinus Serif", 11pt)
+>>> #set par(justify: true)
+>>> #set page(
+>>> "us-letter",
+>>> margin: auto,
+>>> header: align(
+>>> right + horizon,
+>>> title
+>>> ),
+>>> numbering: "1",
+>>> columns: 2,
+>>> )
+>>>
+#show heading.where(
+ level: 1
+): it => block(width: 100%)[
+ #set align(center)
+ #set text(13pt, weight: "regular")
+ #smallcaps(it.body)
+]
+
+#show heading.where(
+ level: 2
+): it => text(
+ size: 11pt,
+ weight: "regular",
+ style: "italic",
+ it.body + [.],
+)
+>>>
+>>> #place(
+>>> top + center,
+>>> float: true,
+>>> scope: "parent",
+>>> clearance: 2em,
+>>> )[
+>>> #text(
+>>> 17pt,
+>>> weight: "bold",
+>>> title,
+>>> )
+>>>
+>>> #grid(
+>>> columns: (1fr, 1fr),
+>>> [
+>>> Therese Tungsten \
+>>> Artos Institute \
+>>> #link("mailto:tung@artos.edu")
+>>> ],
+>>> [
+>>> Dr. John Doe \
+>>> Artos Institute \
+>>> #link("mailto:doe@artos.edu")
+>>> ]
+>>> )
+>>>
+>>> #par(justify: false)[
+>>> *Abstract* \
+>>> #lorem(80)
+>>> ]
+>>> ]
+>>>
+>>> = Introduction
+>>> #lorem(35)
+>>>
+>>> == Motivation
+>>> #lorem(45)
+```
+
+This looks great! We wrote two show rules that each selectively apply to the
+first and second level headings. We used a `where` selector to filter the
+headings by their level. We then rendered the subsection headings as run-ins. We
+also automatically add a period to the end of the subsection headings.
+
+Let's review the conference's style guide:
+- The font should be an 11pt serif font ✓
+- The title should be in 17pt and bold ✓
+- The paper contains a single-column abstract and two-column main text ✓
+- The abstract should be centered ✓
+- The main text should be justified ✓
+- First level section headings should be centered, rendered in small caps and in
+ 13pt ✓
+- Second level headings are run-ins, italicized and have the same size as the
+ body text ✓
+- Finally, the pages should be US letter sized, numbered in the center and the
+ top right corner of each page should contain the title of the paper ✓
+
+We are now in compliance with all of these styles and can submit the paper to
+the conference! The finished paper looks like this:
+
+
+
+## Review
+You have now learned how to create headers and footers, how to use functions and
+scopes to locally override styles, how to create more complex layouts with the
+[`grid`] function and how to write show rules for individual functions, and the
+whole document. You also learned how to use the
+[`where` selector]($styling/#show-rules) to filter the headings by their level.
+
+The paper was a great success! You've met a lot of like-minded researchers at
+the conference and are planning a project which you hope to publish at the same
+venue next year. You'll need to write a new paper using the same style guide
+though, so maybe now you want to create a time-saving template for you and your
+team?
+
+In the next section, we will learn how to create templates that can be reused in
+multiple documents. This is a more advanced topic, so feel free to come back
+to it later if you don't feel up to it right now.
diff --git a/sources/docs/tutorial/4-template.md b/sources/docs/tutorial/4-template.md
new file mode 100644
index 0000000000000000000000000000000000000000..7542cd6e48184e6836311ed5b4696a577b02e3cf
--- /dev/null
+++ b/sources/docs/tutorial/4-template.md
@@ -0,0 +1,406 @@
+---
+description: Typst's tutorial.
+---
+
+# Making a Template
+In the previous three chapters of this tutorial, you have learned how to write a
+document in Typst, apply basic styles, and customize its appearance in-depth to
+comply with a publisher's style guide. Because the paper you wrote in the
+previous chapter was a tremendous success, you have been asked to write a
+follow-up article for the same conference. This time, you want to take the style
+you created in the previous chapter and turn it into a reusable template. In
+this chapter you will learn how to create a template that you and your team can
+use with just one show rule. Let's get started!
+
+## A toy template { #toy-template }
+In Typst, templates are functions in which you can wrap your whole document. To
+learn how to do that, let's first review how to write your very own functions.
+They can do anything you want them to, so why not go a bit crazy?
+
+```example
+#let amazed(term) = box[✨ #term ✨]
+
+You are #amazed[beautiful]!
+```
+
+This function takes a single argument, `term`, and returns a content block with
+the `term` surrounded by sparkles. We also put the whole thing in a box so that
+the term we are amazed by cannot be separated from its sparkles by a line break.
+
+Many functions that come with Typst have optional named parameters. Our
+functions can also have them. Let's add a parameter to our function that lets us
+choose the color of the text. We need to provide a default color in case the
+parameter isn't given.
+
+```example
+#let amazed(term, color: blue) = {
+ text(color, box[✨ #term ✨])
+}
+
+You are #amazed[beautiful]!
+I am #amazed(color: purple)[amazed]!
+```
+
+Templates now work by wrapping our whole document in a custom function like
+`amazed`. But wrapping a whole document in a giant function call would be
+cumbersome! Instead, we can use an "everything" show rule to achieve the same
+with cleaner code. To write such a show rule, put a colon directly after the
+show keyword and then provide a function. This function is given the rest of the
+document as a parameter. The function can then do anything with this content.
+Since the `amazed` function can be called with a single content argument, we can
+just pass it by name to the show rule. Let's try it:
+
+```example
+>>> #let amazed(term, color: blue) = {
+>>> text(color, box[✨ #term ✨])
+>>> }
+#show: amazed
+I choose to focus on the good
+in my life and let go of any
+negative thoughts or beliefs.
+In fact, I am amazing!
+```
+
+Our whole document will now be passed to the `amazed` function, as if we wrapped
+it around it. Of course, this is not especially useful with this particular
+function, but when combined with set rules and named arguments, it can be very
+powerful.
+
+## Embedding set and show rules { #set-and-show-rules }
+To apply some set and show rules to our template, we can use `set` and `show`
+within a content block in our function and then insert the document into
+that content block.
+
+```example
+#let template(doc) = [
+ #set text(font: "Inria Serif")
+ #show "something cool": [Typst]
+ #doc
+]
+
+#show: template
+I am learning something cool today.
+It's going great so far!
+```
+
+Just like we already discovered in the previous chapter, set rules will apply to
+everything within their content block. Since the everything show rule passes our
+whole document to the `template` function, the text set rule and string show
+rule in our template will apply to the whole document. Let's use this knowledge
+to create a template that reproduces the body style of the paper we wrote in the
+previous chapter.
+
+```example
+#let conf(title, doc) = {
+ set page(
+ paper: "us-letter",
+>>> margin: auto,
+ header: align(
+ right + horizon,
+ title
+ ),
+ columns: 2,
+<<< ...
+ )
+ set par(justify: true)
+ set text(
+ font: "Libertinus Serif",
+ size: 11pt,
+ )
+
+ // Heading show rules.
+<<< ...
+>>> show heading.where(
+>>> level: 1
+>>> ): it => block(
+>>> align(center,
+>>> text(
+>>> 13pt,
+>>> weight: "regular",
+>>> smallcaps(it.body),
+>>> )
+>>> ),
+>>> )
+>>> show heading.where(
+>>> level: 2
+>>> ): it => box(
+>>> text(
+>>> 11pt,
+>>> weight: "regular",
+>>> style: "italic",
+>>> it.body + [.],
+>>> )
+>>> )
+
+ doc
+}
+
+#show: doc => conf(
+ [Paper title],
+ doc,
+)
+
+= Introduction
+#lorem(90)
+
+<<< ...
+>>> == Motivation
+>>> #lorem(140)
+>>>
+>>> == Problem Statement
+>>> #lorem(50)
+>>>
+>>> = Related Work
+>>> #lorem(200)
+```
+
+We copy-pasted most of that code from the previous chapter. The two differences
+are this:
+
+1. We wrapped everything in the function `conf` using an everything show rule.
+ The function applies a few set and show rules and echoes the content it has
+ been passed at the end.
+
+2. Moreover, we used a curly-braced code block instead of a content block. This
+ way, we don't need to prefix all set rules and function calls with a `#`. In
+ exchange, we cannot write markup directly in the code block anymore.
+
+Also note where the title comes from: We previously had it inside of a variable.
+Now, we are receiving it as the first parameter of the template function. To do
+so, we passed a closure (that's a function without a name that is used right
+away) to the everything show rule. We did that because the `conf` function
+expects two positional arguments, the title and the body, but the show rule will
+only pass the body. Therefore, we add a new function definition that allows us
+to set a paper title and use the single parameter from the show rule.
+
+## Templates with named arguments { #named-arguments }
+Our paper in the previous chapter had a title and an author list. Let's add
+these things to our template. In addition to the title, we want our template to
+accept a list of authors with their affiliations and the paper's abstract. To
+keep things readable, we'll add those as named arguments. In the end, we want it
+to work like this:
+
+```typ
+#show: doc => conf(
+ title: [Towards Improved Modelling],
+ authors: (
+ (
+ name: "Theresa Tungsten",
+ affiliation: "Artos Institute",
+ email: "tung@artos.edu",
+ ),
+ (
+ name: "Eugene Deklan",
+ affiliation: "Honduras State",
+ email: "e.deklan@hstate.hn",
+ ),
+ ),
+ abstract: lorem(80),
+ doc,
+)
+
+...
+```
+
+Let's build this new template function. First, we add a default value to the
+`title` argument. This way, we can call the template without specifying a title.
+We also add the named `authors` and `abstract` parameters with empty defaults.
+Next, we copy the code that generates title, abstract and authors from the
+previous chapter into the template, replacing the fixed details with the
+parameters.
+
+The new `authors` parameter expects an [array] of [dictionaries]($dictionary)
+with the keys `name`, `affiliation` and `email`. Because we can have an
+arbitrary number of authors, we dynamically determine if we need one, two or
+three columns for the author list. First, we determine the number of authors
+using the [`.len()`]($array.len) method on the `authors` array. Then, we set the
+number of columns as the minimum of this count and three, so that we never
+create more than three columns. If there are more than three authors, a new row
+will be inserted instead. For this purpose, we have also added a `row-gutter`
+parameter to the `grid` function. Otherwise, the rows would be too close
+together. To extract the details about the authors from the dictionary, we use
+the [field access syntax]($scripting/#fields).
+
+We still have to provide an argument to the grid for each author: Here is where
+the array's [`map` method]($array.map) comes in handy. It takes a function as an
+argument that gets called with each item of the array. We pass it a function
+that formats the details for each author and returns a new array containing
+content values. We've now got one array of values that we'd like to use as
+multiple arguments for the grid. We can do that by using the
+[`spread` operator]($arguments). It takes an array and applies each of its items
+as a separate argument to the function.
+
+The resulting template function looks like this:
+
+```typ
+#let conf(
+ title: none,
+ authors: (),
+ abstract: [],
+ doc,
+) = {
+ // Set and show rules from before.
+>>> #set page(columns: 2)
+<<< ...
+
+ set align(center)
+ text(17pt, title)
+
+ let count = authors.len()
+ let ncols = calc.min(count, 3)
+ grid(
+ columns: (1fr,) * ncols,
+ row-gutter: 24pt,
+ ..authors.map(author => [
+ #author.name \
+ #author.affiliation \
+ #link("mailto:" + author.email)
+ ]),
+ )
+
+ par(justify: false)[
+ *Abstract* \
+ #abstract
+ ]
+
+ set align(left)
+ doc
+}
+```
+
+## A separate file { #separate-file }
+Most of the time, a template is specified in a different file and then imported
+into the document. This way, the main file you write in is kept clutter free and
+your template is easily reused. Create a new text file in the file panel by
+clicking the plus button and name it `conf.typ`. Move the `conf` function
+definition inside of that new file. Now you can access it from your main file by
+adding an import before the show rule. Specify the path of the file between the
+`{import}` keyword and a colon, then name the function that you want to import.
+
+Another thing that you can do to make applying templates just a bit more elegant
+is to use the [`.with`]($function.with) method on functions to pre-populate all
+the named arguments. This way, you can avoid spelling out a closure and
+appending the content argument at the bottom of your template list. Templates on
+[Typst Universe]($universe) are designed to work with this style of function
+call.
+
+```example:single
+>>> #let conf(
+>>> title: none,
+>>> authors: (),
+>>> abstract: [],
+>>> doc,
+>>> ) = {
+>>> set text(font: "Libertinus Serif", 11pt)
+>>> set par(justify: true)
+>>> set page(
+>>> "us-letter",
+>>> margin: auto,
+>>> header: align(
+>>> right + horizon,
+>>> title
+>>> ),
+>>> numbering: "1",
+>>> columns: 2,
+>>> )
+>>>
+>>> show heading.where(
+>>> level: 1
+>>> ): it => block(
+>>> align(center,
+>>> text(
+>>> 13pt,
+>>> weight: "regular",
+>>> smallcaps(it.body),
+>>> )
+>>> ),
+>>> )
+>>> show heading.where(
+>>> level: 2
+>>> ): it => box(
+>>> text(
+>>> 11pt,
+>>> weight: "regular",
+>>> style: "italic",
+>>> it.body + [.],
+>>> )
+>>> )
+>>>
+>>> place(
+>>> top,
+>>> float: true,
+>>> scope: "parent",
+>>> clearance: 2em,
+>>> {
+>>> set align(center)
+>>> text(17pt, title)
+>>> let count = calc.min(authors.len(), 3)
+>>> grid(
+>>> columns: (1fr,) * count,
+>>> row-gutter: 24pt,
+>>> ..authors.map(author => [
+>>> #author.name \
+>>> #author.affiliation \
+>>> #link("mailto:" + author.email)
+>>> ]),
+>>> )
+>>> par(justify: false)[
+>>> *Abstract* \
+>>> #abstract
+>>> ]
+>>> },
+>>> )
+>>> doc
+>>>}
+<<< #import "conf.typ": conf
+#show: conf.with(
+ title: [
+ Towards Improved Modelling
+ ],
+ authors: (
+ (
+ name: "Theresa Tungsten",
+ affiliation: "Artos Institute",
+ email: "tung@artos.edu",
+ ),
+ (
+ name: "Eugene Deklan",
+ affiliation: "Honduras State",
+ email: "e.deklan@hstate.hn",
+ ),
+ ),
+ abstract: lorem(80),
+)
+
+= Introduction
+#lorem(90)
+
+== Motivation
+#lorem(140)
+
+== Problem Statement
+#lorem(50)
+
+= Related Work
+#lorem(200)
+```
+
+We have now converted the conference paper into a reusable template for that
+conference! Why not share it in the [Forum](https://forum.typst.app/) or on
+[Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use
+it too?
+
+## Review
+Congratulations, you have completed Typst's Tutorial! In this section, you have
+learned how to define your own functions and how to create and apply templates
+that define reusable document styles. You've made it far and learned a lot. You
+can now use Typst to write your own documents and share them with others.
+
+We are still a super young project and are looking for feedback. If you have any
+questions, suggestions or you found a bug, please let us know
+in the [Forum](https://forum.typst.app/),
+on our [Discord server](https://discord.gg/2uDybryKPe),
+on [GitHub](https://github.com/typst/typst/),
+or via the web app's feedback form (always available in the Help menu).
+
+So what are you waiting for? [Sign up](https://typst.app) and write something!
diff --git a/sources/docs/tutorial/welcome.md b/sources/docs/tutorial/welcome.md
new file mode 100644
index 0000000000000000000000000000000000000000..18b65aef76b8d9aa79a321a4abd5048c6ae1c140
--- /dev/null
+++ b/sources/docs/tutorial/welcome.md
@@ -0,0 +1,44 @@
+---
+description: Typst's tutorial.
+---
+
+# Tutorial
+Welcome to Typst's tutorial! In this tutorial, you will learn how to write and
+format documents in Typst. We will start with everyday tasks and gradually
+introduce more advanced features. This tutorial does not assume prior knowledge
+of Typst, other markup languages, or programming. We do assume that you know how
+to edit a text file.
+
+The best way to start is to sign up to the Typst app for free and follow along
+with the steps below. The app gives you instant preview, syntax highlighting and
+helpful autocompletions. Alternatively, you can follow along in your local text
+editor with the [open-source CLI](https://github.com/typst/typst).
+
+## When to use Typst { #when-typst }
+Before we get started, let's check what Typst is and when to use it. Typst is a
+markup language for typesetting documents. It is designed to be easy to learn,
+fast, and versatile. Typst takes text files with markup in them and outputs
+PDFs.
+
+Typst is a good choice for writing any long form text such as essays, articles,
+scientific papers, books, reports, and homework assignments. Moreover, Typst is
+a great fit for any documents containing mathematical notation, such as papers
+in the math, physics, and engineering fields. Finally, due to its strong styling
+and automation features, it is an excellent choice for any set of documents that
+share a common style, such as a book series.
+
+## What you will learn { #learnings }
+This tutorial has four chapters. Each chapter builds on the previous one. Here
+is what you will learn in each of them:
+
+1. [Writing in Typst:]($tutorial/writing-in-typst) Learn how to write text and
+ insert images, equations, and other elements.
+2. [Formatting:]($tutorial/formatting) Learn how to adjust the formatting
+ of your document, including font size, heading styles, and more.
+3. [Advanced Styling:]($tutorial/advanced-styling) Create a complex page
+ layout for a scientific paper with typographic features such as an author
+ list and run-in headings.
+4. [Making a Template:]($tutorial/making-a-template) Build a reusable template
+ from the paper you created in the previous chapter.
+
+We hope you'll enjoy Typst!
diff --git a/sources/tests/README.md b/sources/tests/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..e625581a3f61418fdfd11bce8a85ff30fa49d127
--- /dev/null
+++ b/sources/tests/README.md
@@ -0,0 +1,150 @@
+# Tests
+
+## Directory structure
+Top level directory structure:
+- `src`: Testing code.
+- `suite`: Input files. Mostly organized in parallel to the code. Each file can
+ contain multiple tests, each of which is a section of Typst code
+ following `--- {name} ---`.
+- `ref`: References which the output is compared with to determine whether a
+ test passed or failed.
+- `store`: Store for PNG, PDF, and SVG output files produced by the tests.
+
+## Running the tests
+Running all tests (including unit tests):
+```bash
+cargo test --workspace
+```
+
+Running just the integration tests (the tests in this directory):
+```bash
+cargo test --workspace --test tests
+```
+
+You may want to [make yourself an alias](#making-an-alias) `testit` so that you can
+write shorter commands. In the examples below, we will use this alias.
+
+Running all tests with the given name pattern. You can use
+[regular expression](https://docs.rs/regex/latest/regex/)s.
+```bash
+testit math # The name has "math" anywhere
+testit math page # The name has "math" or "page" anywhere
+testit "^math" "^page" # The name begins with "math" or "page"
+testit "^(math|page)" # Same as above.
+```
+
+Running all tests discovered under given paths:
+```bash
+testit -p tests/suite/math/attach.typ
+testit -p tests/suite/model -p tests/suite/text
+```
+
+Running tests that begin with `issue` under a given path:
+```bash
+testit "^issue" -p tests/suite/model
+```
+
+Running a test with the exact test name `math-attach-mixed`.
+```bash
+testit --exact math-attach-mixed
+```
+
+You may find more options in the help message:
+```bash
+testit --help
+```
+
+To make the integration tests go faster they don't generate PDFs or SVGs by
+default. Pass the `--pdf` or `--svg` flag to generate those. Mind that PDFs and
+SVGs are **not** tested automatically at the moment, so you should always check
+the output manually when making changes.
+```bash
+testit --pdf
+```
+
+## Writing tests
+The syntax for an individual test is `--- {name} {attr}* ---` followed by some
+Typst code that should be tested. The name must be globally unique in the test
+suite, so that tests can be easily migrated across files. A test name can be
+followed by space-separated attributes. For instance, `--- my-test html ---`
+adds the `html` modifier to `my-test`, instructing the test runner to also
+test HTML output. The following attributes are currently defined:
+
+- `render`: Tests paged output against a reference image (the default, only
+ needs to be specified when `html` is also specified to enable both at the
+ same)
+- `html`: Tests HTML output against a reference HTML file. Disables the `render`
+ default.
+- `large`: Permits a reference image size exceeding 20 KiB. Should be used
+ sparingly.
+
+There are, broadly speaking, three kinds of tests:
+
+- Tests that just ensure that the code runs successfully: Those typically make
+ use of `test` or `assert.eq` (both are very similar, `test` is just shorter)
+ to ensure certain properties hold when executing the Typst code.
+
+- Tests that ensure the code emits particular diagnostic messages: Those have
+ inline annotations like `// Error: 2-7 thing was wrong`. An annotation can
+ start with either "Error", "Warning", or "Hint". The range designates the
+ code span the diagnostic message refers to in the first non-comment line
+ below. If the code span is in a line further below, you can write ranges
+ like `3:2-3:7` to indicate the 2-7 column in the 3rd non-comment line.
+
+- Tests that ensure certain output is produced:
+
+ - Visual output: By default, the compiler produces paged output, renders it
+ with the `typst-render` crate, and compares it against a reference image
+ stored in the repository. The test runner automatically detects whether a
+ test has visual output and requires a reference image in this case.
+
+ To prevent bloat, it is important that the test images are kept as small as
+ possible. To that effect, the test runner enforces a maximum size of 20 KiB.
+ If you're updating a test and hit `reference output size exceeds`, see the
+ section on "Updating reference images" below. If truly necessary, the size
+ limit can be lifted by adding a `large` attribute after the test name, but
+ this should be the case very rarely.
+
+ - HTML output: When a test has the `html` attribute, the compiler produces
+ HTML output and compares it against a reference file stored in the
+ repository. By default, this enables testing of paged output, but you can
+ test both at once by passing both `render` and `html` as attributes.
+
+If you have the choice between writing a test using assertions or using
+reference images, prefer assertions. This makes the test easier to understand
+in isolation and prevents bloat due to images.
+
+## Updating reference images
+If you created a new test or fixed a bug in an existing test, you may need to
+update the reference output used for comparison. For this, you can use the
+`--update` flag:
+```bash
+testit --exact my-test-name --update
+```
+
+For visual tests, this will generally generate compressed reference images (to
+remain within the size limit).
+
+If you use the VS Code test helper extension (see the `tools` folder), you can
+alternatively use the save button to update the reference output.
+
+## Making an alias
+If you want to have a quicker way to run the tests, consider adding a shortcut
+to your shell profile so that you can simply write something like:
+```bash
+testit --exact my-test-name
+```
+
+### Bash
+Open your Bash configuration by executing `nano ~/.bashrc`.
+```bash
+alias testit="cargo test --workspace --test tests --"
+```
+
+### PowerShell
+Open your PowerShell profile by executing `notepad $profile`.
+```ps
+function testit {
+ cargo test --workspace --test tests -- $args
+}
+```
diff --git a/sources/tools/support/README.md b/sources/tools/support/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..e83978de6125e444ae5af7ac91005b32d226907b
--- /dev/null
+++ b/sources/tools/support/README.md
@@ -0,0 +1,13 @@
+# Language support
+This VS Code extension provides minimal language support for Typst. It contains
+a syntax definition and a language configuration for comment toggling,
+autoclosing etc.
+
+The extension was created for development purposes only. It is not maintained
+and its grammar is buggy. For a more actively developed extension see the
+third-party [Tinymist extension](https://github.com/Myriad-Dreamin/tinymist).
+
+## Installation
+The simplest way to install this extension (and keep it up-to-date) is to add a
+symlink from `~/.vscode/extensions/typst-support` to
+`path/to/typst/tools/support`.
diff --git a/sources/tools/test-helper/README.md b/sources/tools/test-helper/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3ecc1d4f4137ee0158578fd3f9c163f3180e5a4f
--- /dev/null
+++ b/sources/tools/test-helper/README.md
@@ -0,0 +1,34 @@
+# Test helper
+
+This is a small VS Code extension that helps with managing Typst's test suite.
+When installed, for all `.typ` files in the `tests` directory, the following
+Code Lens buttons will appear above every test's name:
+
+- View: Opens the output and reference image of a test to the side.
+- Run: Runs the test and shows the results to the side.
+- Save: Runs the test with `--update` to save the reference output.
+- Terminal: Runs the test in the integrated terminal.
+
+In the side panel opened by the Code Lens buttons, there are a few menu buttons
+at the top right:
+
+- Refresh: Reloads the panel to reflect changes to the images.
+- Run: Runs the test and shows the results.
+- Save: Runs the test with `--update` to save the reference output.
+
+## Installation
+In order for VS Code to run the extension with its built-in
+[Node](https://nodejs.org) engine, you need to first build it from source.
+Navigate to `test-helper` directory and build the extension:
+```bash
+npm install # Install the dependencies.
+npm run build # Build the extension from source.
+```
+
+Then, you can easily install it (and keep it up-to-date) via VS Code's UI:
+- Go to View > Command Palette or press Cmd/Ctrl+P,
+- In the drop down list, pick command "Developer: Install Extension from
+ Location",
+- Select this `test-helper` directory in the file explorer dialogue box. VS Code
+ will add the extension's path to `~/.vscode/extensions/extensions.json` (or
+ `%USERPROFILE%\.vscode\extensions\extensions.json` on Windows).
+
+
