{"route":"/en-US-v0.13.1/tutorial/writing-in-typst/","title":"Writing in Typst","description":"Typst's tutorial.","part":null,"outline":[{"id":"figure","name":"Figure","children":[]},{"id":"bibliography","name":"Bibliography","children":[]},{"id":"maths","name":"Maths","children":[]},{"id":"review","name":"Review","children":[]}],"body":{"kind":"html","content":"

Writing in Typst

\n

Let's get started! Suppose you got assigned to write a technical report for\nuniversity. It will contain prose, maths, headings, and figures. To get started,\nyou create a new project on the Typst app. You'll be taken to the editor where\nyou see two panels: A source panel where you compose your document and a\npreview panel where you see the rendered document.

\n

\"Typst

\n

You already have a good angle for your report in mind. So let's start by writing\nthe introduction. Enter some text in the editor panel. You'll notice that the\ntext immediately appears on the previewed page.

\n
In this report, we will explore the\nvarious factors that influence fluid\ndynamics in glaciers and how they\ncontribute to the formation and\nbehaviour of these natural structures.\n
\"Preview\"
\n

Throughout this tutorial, we'll show code examples like this one. Just like in the app, the first panel contains markup and the second panel shows a preview. We shrunk the page to fit the examples so you can see what's going on.

\n

The next step is to add a heading and emphasize some text. Typst uses simple\nmarkup for the most common formatting tasks. To add a heading, enter the =\ncharacter and to emphasize some text with italics, enclose it in\n_underscores_.

\n
= Introduction\nIn this report, we will explore the\nvarious factors that influence _fluid\ndynamics_ in glaciers and how they\ncontribute to the formation and\nbehaviour of these natural structures.\n
\"Preview\"
\n

That was easy! To add a new paragraph, just add a blank line in between two\nlines of text. If that paragraph needs a subheading, produce it by typing ==\ninstead of =. The number of = characters determines the nesting level of the\nheading.

\n

Now we want to list a few of the circumstances that influence glacier dynamics.\nTo do that, we use a numbered list. For each item of the list, we type a +\ncharacter at the beginning of the line. Typst will automatically number the\nitems.

\n
+ The climate\n+ The topography\n+ The geology\n
\"Preview\"
\n

If we wanted to add a bulleted list, we would use the - character instead of\nthe + character. We can also nest lists: For example, we can add a sub-list to\nthe first item of the list above by indenting it.

\n
+ The climate\n  - Temperature\n  - Precipitation\n+ The topography\n+ The geology\n
\"Preview\"
\n

Adding a figure

\n

You think that your report would benefit from a figure. Let's add one. Typst\nsupports images in the formats PNG, JPEG, GIF, and SVG. To add an image file to\nyour project, first open the file panel by clicking the box icon in the left\nsidebar. Here, you can see a list of all files in your project. Currently, there\nis only one: The main Typst file you are writing in. To upload another file,\nclick the button with the arrow in the top-right corner. This opens the upload\ndialog, in which you can pick files to upload from your computer. Select an\nimage file for your report.

\n

\"Upload

\n

We have seen before that specific symbols (called markup) have specific\nmeaning in Typst. We can use =, -, +, and _ to create headings, lists\nand emphasized text, respectively. However, having a special symbol for\neverything we want to insert into our document would soon become cryptic and\nunwieldy. For this reason, Typst reserves markup symbols only for the most\ncommon things. Everything else is inserted with functions. For our image to\nshow up on the page, we use Typst's image function.

\n
#image("glacier.jpg")\n
\"Preview\"
\n

In general, a function produces some output for a set of arguments. When you\ncall a function within markup, you provide the arguments and Typst inserts the\nresult (the function's return value) into the document. In our case, the\nimage function takes one argument: The path to the image file. To call a\nfunction in markup, we first need to type the # character, immediately\nfollowed by the name of the function. Then, we enclose the arguments in\nparentheses. Typst recognizes many different data types within argument lists.\nOur file path is a short string of text, so we need to enclose it in\ndouble quotes.

\n

The inserted image uses the whole width of the page. To change that, pass the\nwidth argument to the image function. This is a named argument and\ntherefore specified as a name: value pair. If there are multiple arguments,\nthey are separated by commas, so we first need to put a comma behind the path.

\n
#image("glacier.jpg", width: 70%)\n
\"Preview\"
\n

The width argument is a relative length. In our case, we\nspecified a percentage, determining that the image shall take up 70% of the\npage's width. We also could have specified an absolute value like 1cm or\n0.7in.

\n

Just like text, the image is now aligned at the left side of the page by\ndefault. It's also lacking a caption. Let's fix that by using the figure\nfunction. This function takes the figure's contents as a positional argument and\nan optional caption as a named argument.

\n

Within the argument list of the figure function, Typst is already in code\nmode. This means, you now have to remove the hash before the image function call.\nThe hash is only needed directly in markup (to disambiguate text from function\ncalls).

\n

The caption consists of arbitrary markup. To give markup to a function, we\nenclose it in square brackets. This construct is called a content block.

\n
#figure(\n  image("glacier.jpg", width: 70%),\n  caption: [\n    _Glaciers_ form an important part\n    of the earth's climate system.\n  ],\n)\n
\"Preview\"
\n

You continue to write your report and now want to reference the figure. To do\nthat, first attach a label to figure. A label uniquely identifies an element in\nyour document. Add one after the figure by enclosing some name in angle\nbrackets. You can then reference the figure in your text by writing an @\nsymbol followed by that name. Headings and equations can also be labelled to\nmake them referenceable.

\n
Glaciers as the one shown in\n@glaciers will cease to exist if\nwe don't take action soon!\n\n#figure(\n  image("glacier.jpg", width: 70%),\n  caption: [\n    _Glaciers_ form an important part\n    of the earth's climate system.\n  ],\n) <glaciers>\n
\"Preview\"
\n

So far, we've passed content blocks (markup in square brackets) and strings\n(text in double quotes) to our functions. Both seem to contain text. What's the\ndifference?

\n

A content block can contain text, but also any other kind of markup, function\ncalls, and more, whereas a string is really just a sequence of characters and\nnothing else.

\n

For example, the image function expects a path to an image file.\nIt would not make sense to pass, e.g., a paragraph of text or another image as\nthe image's path parameter. That's why only strings are allowed here.\nOn the contrary, strings work wherever content is expected because text is a\nvalid kind of content.

\n
\n

Adding a bibliography

\n

As you write up your report, you need to back up some of your claims. You can\nadd a bibliography to your document with the bibliography function. This\nfunction expects a path to a bibliography file.

\n

Typst's native bibliography format is\nHayagriva,\nbut for compatibility you can also use BibLaTeX files. As your classmate has\nalready done a literature survey and sent you a .bib file, you'll use that\none. Upload the file through the file panel to access it in Typst.

\n

Once the document contains a bibliography, you can start citing from it.\nCitations use the same syntax as references to a label. As soon as you cite a\nsource for the first time, it will appear in the bibliography section of your\ndocument. Typst supports different citation and bibliography styles. Consult the\nreference for more details.

\n
= Methods\nWe follow the glacier melting models\nestablished in @glacier-melt.\n\n#bibliography("works.bib")\n
\"Preview\"
\n

Maths

\n

After fleshing out the methods section, you move on to the meat of the document:\nYour equations. Typst has built-in mathematical typesetting and uses its own\nmath notation. Let's start with a simple equation. We wrap it in $ signs\nto let Typst know it should expect a mathematical expression:

\n
The equation $Q = rho A v + C$\ndefines the glacial flow rate.\n
\"Preview\"
\n

The equation is typeset inline, on the same line as the surrounding text. If you\nwant to have it on its own line instead, you should insert a single space at its\nstart and end:

\n
The flow rate of a glacier is\ndefined by the following equation:\n\n$ Q = rho A v + C $\n
\"Preview\"
\n

We can see that Typst displayed the single letters Q, A, v, and C as-is,\nwhile it translated rho into a Greek letter. Math mode will always show single\nletters verbatim. Multiple letters, however, are interpreted as symbols,\nvariables, or function names. To imply a multiplication between single letters,\nput spaces between them.

\n

If you want to have a variable that consists of multiple letters, you can\nenclose it in quotes:

\n
The flow rate of a glacier is given\nby the following equation:\n\n$ Q = rho A v + "time offset" $\n
\"Preview\"
\n

You'll also need a sum formula in your paper. We can use the sum symbol and\nthen specify the range of the summation in sub- and superscripts:

\n
Total displaced soil by glacial flow:\n\n$ 7.32 beta +\n  sum_(i=0)^nabla Q_i / 2 $\n
\"Preview\"
\n

To add a subscript to a symbol or variable, type a _ character and then the\nsubscript. Similarly, use the ^ character for a superscript. If your\nsub- or superscript consists of multiple things, you must enclose them\nin round parentheses.

\n

The above example also showed us how to insert fractions: Simply put a /\ncharacter between the numerator and the denominator and Typst will automatically\nturn it into a fraction. Parentheses are smartly resolved, so you can enter your\nexpression as you would into a calculator and Typst will replace parenthesized\nsub-expressions with the appropriate notation.

\n
Total displaced soil by glacial flow:\n\n$ 7.32 beta +\n  sum_(i=0)^nabla\n    (Q_i (a_i - epsilon)) / 2 $\n
\"Preview\"
\n

Not all math constructs have special syntax. Instead, we use functions, just\nlike the image function we have seen before. For example, to insert a column\nvector, we can use the vec function. Within math mode, function\ncalls don't need to start with the # character.

\n
$ v := vec(x_1, x_2, x_3) $\n
\"Preview\"
\n

Some functions are only available within math mode. For example, the\ncal function is used to typeset calligraphic letters commonly\nused for sets. The math section of the reference provides a\ncomplete list of all functions that math mode makes available.

\n

One more thing: Many symbols, such as the arrow, have a lot of variants. You can\nselect among these variants by appending a dot and a modifier name to a symbol's\nname:

\n
$ a arrow.squiggly b $\n
\"Preview\"
\n

This notation is also available in markup mode, but the symbol name must be\npreceded with #sym. there. See the symbols section\nfor a list of all available symbols.

\n

Review

\n

You have now seen how to write a basic document in Typst. You learned how to\nemphasize text, write lists, insert images, align content, and typeset\nmathematical expressions. You also learned about Typst's functions. There are\nmany more kinds of content that Typst lets you insert into your document, such\nas tables, shapes, and code blocks. You\ncan peruse the reference to learn more about these and other features.

\n

For the moment, you have completed writing your report. You have already saved a\nPDF by clicking on the download button in the top right corner. However, you\nthink the report could look a bit less plain. In the next section, we'll learn\nhow to customize the look of our document.

"}}