{"route":"/en-US-v0.14.1/tutorial/advanced-styling/","title":"Advanced Styling","description":"Typst's tutorial.","part":null,"outline":[{"id":"guidelines","name":"Guidelines","children":[]},{"id":"set-rules","name":"Set Rules","children":[]},{"id":"title-and-abstract","name":"Title And Abstract","children":[]},{"id":"columns-and-headings","name":"Columns And Headings","children":[]},{"id":"review","name":"Review","children":[]}],"body":{"kind":"html","content":"

Advanced Styling

\n

In the previous two chapters of this tutorial, you have learned how to write a\ndocument in Typst and how to change its formatting. The report you wrote\nthroughout the last two chapters got a straight A and your supervisor wants to\nbase a conference paper on it! The report will of course have to comply with the\nconference's style guide. Let's see how we can achieve that.

\n

Before we start, let's create a team, invite your supervisor and add them to the\nteam. You can do this by going back to the app dashboard with the back icon in\nthe top left corner of the editor. Then, choose the plus icon in the left\ntoolbar and create a team. Finally, click on the new team and go to its settings\nby clicking 'manage team' next to the team name. Now you can invite your\nsupervisor by email.

\n

\"The

\n

Next, move your project into the team: Open it, going to its settings by\nchoosing the gear icon in the left toolbar and selecting your new team from the\nowners dropdown. Don't forget to save your changes!

\n

Now, your supervisor can also edit the project and you can both see the changes\nin real time. You can join our Discord server\nto find other users and try teams with them!

\n

The conference guidelines

\n

The layout guidelines are available on the conference website. Let's take a look\nat them:

\n\n

We already know how to do many of these things, but for some of them, we'll need\nto learn some new tricks.

\n

Writing the right set rules

\n

Let's start by writing some set rules for the document.

\n
#set page(\n  paper: "us-letter",\n  header: align(right)[\n    A Fluid Dynamic Model for\n    Glacier Flow\n  ],\n  numbering: "1",\n)\n#set par(justify: true)\n#set text(\n  font: "Libertinus Serif",\n  size: 11pt,\n)\n\n#lorem(600)\n
\"Preview\"
\n

You are already familiar with most of what is going on here. We set the text\nsize to 11pt and the font to Libertinus Serif. We also enable paragraph\njustification and set the page size to US letter.

\n

The header argument is new: With it, we can provide content to fill the top\nmargin of every page. In the header, we specify our paper's title as requested\nby the conference style guide. We use the align function to align the text to\nthe right.

\n

Last but not least is the numbering argument. Here, we can provide a\nnumbering pattern that defines how to number the pages. By\nsetting it to "1", Typst only displays the bare page number. Setting it to\n"(1/1)" would have displayed the current page and total number of pages\nsurrounded by parentheses. And we could even have provided a completely custom\nfunction here to format things to our liking.

\n

Creating a title and abstract

\n

Now, let's add a title and an abstract. We'll start with the title. Typst comes\nwith a title function. Let's start by providing our title as an argument:

\n
#title[\n  A Fluid Dynamic Model\n  for Glacier Flow\n]\n
\"Preview\"
\n

You can see that the title is already boldfaced and has some space around it.\nHowever, it is left-aligned and not exactly 17pt large. Hence, we need to adjust\nits appearance. The title function does not come with any arguments for\nfont or text size we could set. Instead, these properties are defined on the\ntext and align functions.

\n
\n

What is the difference between what the title function inserted and the\nheadings we produced with equals signs?

\n

Headings, even first-level headings, can appear multiple times in your document\nwhereas a title only appears once, usually at the beginning. Differentiating\nbetween the two helps Typst make your document accessible for users of\nAssistive Technology such as screen readers.

\n
\n

When we want to customize the properties of some element inside of another kind\nof element, we can use show-set rules. First, we use show to select which\nelement we want to customize. We call this a selector. Then, we type a colon.\nNext, we write the set rule that should apply to elements matching the selector.\nSummarized, the syntax looks like this:

\n
#show your-selector: set some-element(/* ... */)\n
\n

Let's recall: We want to center-align the title and make it 17pt large. Hence,\nwe need two show-set rules:

\n\n

Our example now looks like this:

\n
#show title: set text(size: 17pt)\n#show title: set align(center)\n\n#title[\n  A Fluid Dynamic Model\n  for Glacier Flow\n]\n
\"Preview\"
\n

This looks right. Let's also add the author list: Since we are writing this\npaper together with our supervisor, we'll add our own and their name.

\n
\n#grid(\n  columns: (1fr, 1fr),\n  align(center)[\n    Therese Tungsten \\\n    Artos Institute \\\n    #link("mailto:tung@artos.edu")\n  ],\n  align(center)[\n    Dr. John Doe \\\n    Artos Institute \\\n    #link("mailto:doe@artos.edu")\n  ]\n)\n
\"Preview\"
\n

The two author blocks are laid out next to each other. We use the grid\nfunction to create this layout. With a grid, we can control exactly how large\neach column is and which content goes into which cell. The columns argument\ntakes an array of relative lengths or fractions. In\nthis case, we passed it two equal fractional sizes, telling it to split the\navailable space into two equal columns. We then passed two content arguments to\nthe grid function. The first with our own details, and the second with our\nsupervisors'. We again use the align function to center the content within the\ncolumn. The grid takes an arbitrary number of content arguments specifying the\ncells. Rows are added automatically, but they can also be manually sized with\nthe rows argument.

\n

Looking at the authors and the title, they are a bit too close together. You can\naddress this by using another show-set rule to configure the space below the\ntitle. The title, the grid, paragraphs, and all other elements that Typst\narranges from the top to the bottom of the page are called blocks. Each block\nis controlled by the block function. It controls behaviors like their\ndistance and whether a block can contain a page break. That means that we can\nwrite another show-set rule that selects the title to set the block spacing:

\n
#show title: set text(size: 17pt)\n#show title: set align(center)\n#show title: set block(below: 1.2em)\n\n#title[\n  A Fluid Dynamic Model\n  for Glacier Flow\n]\n\n#grid(\n  // ...\n)\n
\"Preview\"
\n

With this show-set rule, we overrode the spacing below the title. We have used\nthe em unit: It allows us to express lengths as multiples of the font size.\nHere, we used it to space the title and the author list exactly 1.2× the font\nsize apart. Now, let's add the abstract. Remember that the conference wants the\nabstract to be set ragged and centered.

\n
...\n\n#align(center)[\n  #set par(justify: false)\n  *Abstract* \\\n  #lorem(80)\n]\n
\"Preview\"
\n

Well done! One notable thing is that we used a set rule within the content\nargument of align to turn off justification for the abstract. This does not\naffect the remainder of the document even though it was specified after the\nfirst set rule because content blocks scope styling. Anything set within a\ncontent block will only affect the content within that block.

\n

Another tweak could be to remove the duplication between the header and the\ntitle element's argument. Since they share the title, it would be convenient to\nstore it in a place designed to hold metadata about the document. We would then\nneed a way to retrieve the title in both places. The document element can help\nus with the former: By using it in a set rule, we can store document metadata\nlike title, description, and keywords.

\n
#set document(title: [A Fluid Dynamic Model for Glacier Flow])\n
\n

When exporting a PDF, the title set here will appear in the title bar of your\nPDF reader. Your operating system will also use this title to make the file\nretrievable with search. Last but not least, it contributes to making your\ndocument more accessible and is required if you choose to comply with PDF/UA, a\nPDF standard focused on accessibility.

\n

Now, we need a way to retrieve the value we set in the main title and the\nheader. Because the title function is designed to work together with the\ndocument element, calling it with no arguments will just print the title. For\nthe header, we will need to be more explicit: Because Typst has no way of\nknowing that we want to insert the title there, we will need to tell it to do so\nmanually.

\n

Using context, we can retrieve the contents of any values we have set on\nelements before. When we use the context keyword, we can access any property\nof any element, including the document element's title property. Its use looks\nlike this:

\n
#set document(title: [\n  A Fluid Dynamic Model\n  for Glacier Flow\n])\n\n...\n\n#set page(\n  header: align(\n    right + horizon,\n    // Retrieve the document\n    // element's title property.\n    context document.title,\n  ),\n  ...\n)\n\n#title()\n\n...\n\n
\"Preview\"
\n

First, notice how we called the title function with empty, round\nparentheses. Because no argument was passed, it defaulted to what we set for the\ndocument element above. The distinction between empty round and empty square\nbrackets is important: While empty round brackets show that you are passing\nnothing, empty square brackets mean that you are passing one argument: an empty\ncontent block. If called that way, the title would have no visible content.

\n

Next, take a look at the header. Instead of the title in square parentheses, we\nused the context keyword to access the document title. This inserted exactly\nwhat we set above. The role of context is not limited to accessing properties:\nWith it, you can check if some elements are present in the document, measure the\nphysical dimensions of others, and more. Using context, you can build powerful\ntemplates that react to the preferences of the end-user.

\n
\n
\n\nWhy is the context keyword required to access element properties?\n\n

Normally, when we access a variable, we know exactly what its value is going to\nbe:

\n\n

However, sometimes, that's not enough. In this chapter of the tutorial, we have\ninserted a page header with the title. Even though we pass only one piece of\ncontent for the header, we may want different pages to have different headers.\nFor example, we may want to print the chapter name or use the page number. When\nwe use context, we can write a single context block that tells Typst to take a\nlook at where it's inserted, look for the last heading, the current page number,\nor anything else, and go from there. That means that the same context block,\ninserted on different pages, can produce different output.

\n

For more information, read up on context in its docs after\ncompleting this tutorial.

\n
\n
\n

Adding columns and headings

\n

The paper above unfortunately looks like a wall of lead. To fix that, let's add\nsome headings and switch our paper to a two-column layout. Fortunately, that's\neasy to do: We just need to amend our page set rule with the columns\nargument.

\n

By adding columns: 2 to the argument list, we have wrapped the whole\ndocument in two columns. However, that would also affect the title and authors\noverview. To keep them spanning the whole page, we can wrap them in a function\ncall to place. Place expects an alignment and the content it\nshould place as positional arguments. Using the named scope argument, we can\ndecide if the items should be placed relative to the current column or its\nparent (the page). There is one more thing to configure: If no other arguments\nare provided, place takes its content out of the flow of the document and\npositions it over the other content without affecting the layout of other\ncontent in its container:

\n
#place(\n  top + center,\n  rect(fill: black),\n)\n#lorem(30)\n
\"Preview\"
\n

If we hadn't used place here, the square would be in its own line, but here\nit overlaps the few lines of text following it. Likewise, that text acts as if\nthere was no square. To change this behavior, we can pass the argument\nfloat: true to ensure that the space taken up by the placed item at the top\nor bottom of the page is not occupied by any other content.

\n
#set page(\n  paper: "us-letter",\n  header: align(\n    right + horizon,\n    context document.title,\n  ),\n  numbering: "1",\n  columns: 2,\n)\n\n#place(\n  top + center,\n  float: true,\n  scope: "parent",\n  clearance: 2em,\n)[\n  ...\n\n  #par(justify: false)[\n    *Abstract* \\\n    #lorem(80)\n  ]\n]\n\n= Introduction\n#lorem(300)\n\n= Related Work\n#lorem(200)\n
\"Preview\"
\n

In this example, we also used the clearance argument of the place function\nto provide the space between it and the body instead of using the v\nfunction. We can also remove the explicit align(center, ..) calls around the\nvarious parts since they inherit the center alignment from the placement.

\n

Now there is only one thing left to do: Style our headings. We need to make them\ncentered and use small capitals. These properties are not available on the\nheading function, so we will need to write a few show-set rules and a show\nrule:

\n\n
#show heading: set align(center)\n#show heading: set text(\n  size: 13pt,\n  weight: "regular",\n)\n#show heading: smallcaps\n\n...\n\n= Introduction\n...\n\n== Motivation\n...\n
\"Preview\"
\n

This looks great! We used show rules that apply to all headings. In the final\nshow rule, we applied the smallcaps function to the complete heading. As we\nwill see in the next example, we can also provide a custom rule to completely\noverride the default look of headings.

\n

The only remaining problem is that all headings look the same now. The\n"Motivation" and "Problem Statement" subsections ought to be italic run-in\nheaders, but right now, they look indistinguishable from the section headings.\nWe can fix that by using a where selector on our show rule: This is a\nmethod we can call on headings (and other elements) that\nallows us to filter them by their properties. We can use it to differentiate\nbetween section and subsection headings:

\n
#show heading.where(level: 1): set align(center)\n#show heading.where(level: 1): set text(size: 13pt, weight: "regular")\n#show heading.where(level: 1): smallcaps\n\n#show heading.where(level: 2): set text(\n  size: 11pt,\n  weight: "regular",\n  style: "italic",\n)\n#show heading.where(level: 2): it => {\n  it.body + [.]\n}\n
\"Preview\"
\n

In this example, we first scope our previous rules to first-level headings by\nusing .where(level: 1) to make the selector more specific. Then, we add a\nshow-set rule for the second heading level. Finally, we need a show rule with a\ncustom function: Headings enclose their contents with a block by default. This\nhas the effect that the heading gets its own line. However, we want it to run\ninto the text, so we need to provide our own show rule to get rid of this block.

\n

We provide the rule with a function that takes the heading as a parameter.\nThis parameter is conventionally called it, but can have another name. The\nparameter can be used as content and will just display the whole default\nheading. Alternatively, when we want to build our own heading instead, we can\nuse its fields like body, numbering, and level to compose a custom look.\nHere, we are just printing the body of the heading with a trailing dot and leave\nout the block that the built-in show rule produces. Note that this heading will\nno longer react to set rules for heading numbering and similar because we did\nnot explicitly use it.numbering in the show rule. If you are writing show\nrules like this and want the document to remain customizable, you will need to\ntake these fields into account.

\n

This looks great! We wrote show rules that selectively apply to the first and\nsecond level headings. We used a where selector to filter the headings by\ntheir level. We then rendered the subsection headings as run-ins. We\nalso automatically add a period to the end of the subsection headings.

\n

Let's review the conference's style guide:

\n\n

We are now in compliance with all of these styles and can submit the paper to\nthe conference! The finished paper looks like this:

\n

\n

Review

\n

You have now learned how to create titles, headers, and footers, how to use\nfunctions, show-set rules, and scopes to locally override styles, how to create\nmore complex layouts with the grid function, how to access element\nproperties with context, and how to write show rules for individual functions,\nand the whole document. You also learned how to use the where\nselector to filter the headings by their level.

\n

The paper was a great success! You've met a lot of like-minded researchers at\nthe conference and are planning a project which you hope to publish at the same\nvenue next year. You'll need to write a new paper using the same style guide\nthough, so maybe now you want to create a time-saving template for you and your\nteam?

\n

In the next section, we will learn how to create templates that can be reused in\nmultiple documents. This is a more advanced topic, so feel free to come back\nto it later if you don't feel up to it right now.

"}}