{"route":"/en-US-v0.14.1/tutorial/formatting/","title":"Formatting","description":"Typst's tutorial.","part":null,"outline":[{"id":"set-rules","name":"Set rules","children":[]},{"id":"autocomplete","name":"Autocomplete","children":[]},{"id":"page-setup","name":"Page Setup","children":[]},{"id":"sophistication","name":"Sophistication","children":[]},{"id":"show-rules","name":"Show rules","children":[]},{"id":"review","name":"Review","children":[]}],"body":{"kind":"html","content":"

Formatting

\n

So far, you have written a report with some text, a few equations and images.\nHowever, it still looks very plain. Your teaching assistant does not yet know\nthat you are using a new typesetting system, and you want your report to fit in\nwith the other student's submissions. In this chapter, we will see how to format\nyour report using Typst's styling system.

\n

Set rules

\n

As we have seen in the previous chapter, Typst has functions that insert\ncontent (e.g. the image function) and others that manipulate content that\nthey received as arguments (e.g. the align function). The first impulse you\nmight have when you want, for example, to change the font, could be to look\nfor a function that does that and wrap the complete document in it.

\n
#text(font: "New Computer Modern")[\n  = Background\n  In the case of glaciers, fluid\n  dynamics principles can be used\n  to understand how the movement\n  and behaviour of the ice is\n  influenced by factors such as\n  temperature, pressure, and the\n  presence of other fluids (such as\n  water).\n]\n
\"Preview\"
\n

Wait, shouldn't all arguments of a function be specified within parentheses? Why\nis there a second set of square brackets with content after the parentheses?\nThe answer is that, as passing content to a function is such a common thing to\ndo in Typst, there is special syntax for it: Instead of putting the content\ninside of the argument list, you can write it in square brackets directly after\nthe normal arguments, saving on punctuation.

\n

As seen above, that works. With the text function, we can adjust the font\nfor all text within it. However, wrapping the document in countless functions\nand applying styles selectively and in-situ can quickly become cumbersome.

\n

Fortunately, Typst has a more elegant solution. With set rules, you can apply\nstyle properties to all occurrences of some kind of content. You write a set\nrule by entering the set keyword, followed by the name of the function whose\nproperties you want to set, and a list of arguments in parentheses.

\n
#set text(\n  font: "New Computer Modern"\n)\n\n= Background\nIn the case of glaciers, fluid\ndynamics principles can be used\nto understand how the movement\nand behaviour of the ice is\ninfluenced by factors such as\ntemperature, pressure, and the\npresence of other fluids (such as\nwater).\n
\"Preview\"
\n

Want to know in more technical terms what is happening here?

\n

Set rules can be conceptualized as setting default values\nfor some of the parameters of a function for all future\nuses of that function.

\n
\n

The autocomplete panel

\n

If you followed along and tried a few things in the app, you might have noticed\nthat always after you enter a # character, a panel pops up to show you the\navailable functions, and, within an argument list, the available parameters.\nThat's the autocomplete panel. It can be very useful while you are writing your\ndocument: You can apply its suggestions by hitting the Return key or navigate to\nthe desired completion with the arrow keys. The panel can be dismissed by\nhitting the Escape key and opened again by typing # or hitting\nCtrl + Space. Use the autocomplete panel to discover the\nright arguments for functions. Most suggestions come with a small description of\nwhat they do.

\n

\"Autocomplete

\n

Set up the page

\n

Back to set rules: When writing a rule, you choose the function depending on\nwhat type of element you want to style. Here is a list of some functions that\nare commonly used in set rules:

\n\n

Not all function parameters can be set. In general, only parameters that tell\na function how to do something can be set, not those that tell it what to\ndo it with. The function reference pages indicate which parameters are settable.

\n

Let's add a few more styles to our document. We want larger margins and a serif\nfont. For the purposes of the example, we'll also set another page size.

\n
#set page(\n  paper: "a6",\n  margin: (x: 1.8cm, y: 1.5cm),\n)\n#set text(\n  font: "New Computer Modern",\n  size: 10pt\n)\n#set par(\n  justify: true,\n  leading: 0.52em,\n)\n\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\n...\n\n#align(center + bottom)[\n  #image("glacier.jpg", width: 70%)\n\n  *Glaciers form an important\n  part of the earth's climate\n  system.*\n]\n
\"Preview\"
\n

There are a few things of note here.

\n

First is the page set rule. It receives two arguments: the page size and\nmargins for the page. The page size is a string. Typst accepts many standard\npage sizes, but you can also specify a custom page size. The\nmargins are specified as a dictionary. Dictionaries are a\ncollection of key-value pairs. In this case, the keys are x and y, and the\nvalues are the horizontal and vertical margins, respectively. We could also have\nspecified separate margins for each side by passing a dictionary with the keys\nleft, right, top, and bottom.

\n

Next is the set text set rule. Here, we set the font size to 10pt and\nfont family to "New Computer Modern". The Typst app comes with many fonts\nthat you can try for your document. When you are in the text function's argument\nlist, you can discover the available fonts in the autocomplete panel.

\n

We have also set the spacing between lines (a.k.a. leading): It is specified as\na length value, and we used the em unit to specify the leading relative to\nthe size of the font: 1em is equivalent to the current font size (which\ndefaults to 11pt).

\n

Finally, we have bottom aligned our image by adding a vertical alignment to our\ncenter alignment. Vertical and horizontal alignments can be combined with the\n+ operator to yield a 2D alignment.

\n

A hint of sophistication

\n

To structure our document more clearly, we now want to number our headings. We\ncan do this by setting the numbering parameter of the heading function.

\n
#set heading(numbering: "1.")\n\n= Introduction\n#lorem(10)\n\n== Background\n#lorem(12)\n\n== Methods\n#lorem(15)\n
\"Preview\"
\n

We specified the string "1." as the numbering parameter. This tells Typst to\nnumber the headings with arabic numerals and to put a dot between the number of\neach level. We can also use letters, roman numerals, and symbols\nfor our headings:

\n
#set heading(numbering: "1.a")\n\n= Introduction\n#lorem(10)\n\n== Background\n#lorem(12)\n\n== Methods\n#lorem(15)\n
\"Preview\"
\n

This example also uses the lorem function to generate some placeholder text.\nThis function takes a number as an argument and generates that many words of\nLorem Ipsum text.

\n
\n

Did you wonder why the headings and text set rules apply to all text and headings,\neven if they are not produced with the respective functions?

\n

Typst internally calls the heading function every time you write\n= Conclusion. In fact, the function call #heading[Conclusion] is\nequivalent to the heading markup above. Other markup elements work similarly,\nthey are only syntax sugar for the corresponding function calls.

\n
\n

Show rules

\n

You are already pretty happy with how this turned out. But one last thing needs\nto be fixed: The report you are writing is intended for a larger project and\nthat project's name should always be accompanied by a logo, even in prose.

\n

You consider your options. You could add an #image("logo.svg") call before\nevery instance of the logo using search and replace. That sounds very tedious.\nInstead, you could maybe\ndefine a custom function that always yields the\nlogo with its image. However, there is an even easier way:

\n

With show rules, you can redefine how Typst displays certain elements. You\nspecify which elements Typst should show differently and how they should look.\nShow rules can be applied to instances of text, many functions, and even the\nwhole document.

\n
#show "ArtosFlow": name => box[\n  #box(image(\n    "logo.svg",\n    height: 0.7em,\n  ))\n  #name\n]\n\nThis report is embedded in the\nArtosFlow project. ArtosFlow is a\nproject of the Artos Institute.\n
\"Preview\"
\n

There is a lot of new syntax in this example: We write the show keyword,\nfollowed by a string of text we want to show differently and a colon. Then, we\nwrite a function that takes the content that shall be shown as an argument.\nHere, we called that argument name. We can now use the name variable in the\nfunction's body to print the ArtosFlow name. Our show rule adds the logo image\nin front of the name and puts the result into a box to prevent linebreaks from\noccurring between logo and name. The image is also put inside of a box, so that\nit does not appear in its own paragraph.

\n

The calls to the first box function and the image function did not require a\nleading # because they were not embedded directly in markup. When Typst\nexpects code instead of markup, the leading # is not needed to access\nfunctions, keywords, and variables. This can be observed in parameter lists,\nfunction definitions, and code blocks.

\n

Review

\n

You now know how to apply basic formatting to your Typst documents. You learned\nhow to set the font, justify your paragraphs, change the page dimensions, and\nadd numbering to your headings with set rules. You also learned how to use a\nbasic show rule to change how text appears throughout your document.

\n

You have handed in your report. Your supervisor was so happy with it that they\nwant to adapt it into a conference paper! In the next section, we will learn how\nto format your document as a paper using more advanced show rules and functions.

"}}