{"route":"/en-US-v0.14.1/tutorial/making-a-template/","title":"Making a Template","description":"Typst's tutorial.","part":null,"outline":[{"id":"variables","name":"Variables","children":[]},{"id":"toy-template","name":"Toy Template","children":[]},{"id":"set-and-show-rules","name":"Set And Show Rules","children":[]},{"id":"named-arguments","name":"Named Arguments","children":[]},{"id":"separate-file","name":"Separate File","children":[]},{"id":"review","name":"Review","children":[]}],"body":{"kind":"html","content":"

Making a Template

\n

In the previous three chapters of this tutorial, you have learned how to write a\ndocument in Typst, apply basic styles, and customize its appearance in-depth to\ncomply with a publisher's style guide. Because the paper you wrote in the\nprevious chapter was a tremendous success, you have been asked to write a\nfollow-up article for the same conference. This time, you want to take the style\nyou created in the previous chapter and turn it into a reusable template. In\nthis chapter you will learn how to create a template that you and your team can\nuse with just one show rule. Let's get started!

\n

Reusing data with variables

\n

In the past chapters, most of the content of the document was entered by hand.\nIn the third chapter, we used the document element and context to cut down on\nrepetition and only enter the title once. But in practice, there may be many\nmore things that occur multiple times in your document. There are multiple good\nreasons to just define these repeated values once:

\n
    \n
  1. It makes changing them later easier
    2. \n
  2. It allows you to quickly find all instances where you used something
    3. \n
  3. It makes it easy to be consistent throughout
    4. \n
  4. For long or hard-to-enter repeated segments, a shorter variable name is often\nmore convenient to type
    5. \n
\n

If you were using a conventional word processor, you might resort to using a\nplaceholder value that you can later search for. In Typst, however, you can\ninstead use variables to safely store content and reuse it across your whole\ndocument through a variable name.

\n

The technique of using context to reproduce an element's property we have\nlearned earlier is not always the most appropriate for this: Typst's built-in\nelements focus on semantic properties like the title and description of a\ndocument, or things that directly relate to typesetting, like the text size.

\n

For our example, we want to take a look at Typst's pronunciation. One of the\nbest ways to transcribe pronunciation is the International Phonetic Alphabet\n(IPA). But because it uses characters not found on common keyboards, typing IPA\nrepeatedly can become cumbersome. So let's instead define a variable that we can\nreference multiple times.

\n
#let ipa = [taɪpst]\n
\n

Here, we use a new keyword, let, to indicate a variable definition. Then,\nwe put the name of our variable, in this case, ipa. Finally, we type an equals\nsign and the value of our variable. It is enclosed in square brackets because\nit is content, mirroring how you would call a function accepting content. In\nother words, this syntax mirrors the phrase "Let the variable ipa have the\nvalue [taɪpst]."

\n

Now, we can use the variable in our document:

\n
#let ipa = [taɪpst]\n\nThe canonical way to\npronounce Typst is #ipa.\n\n#table(\n  columns: (1fr, 1fr),\n  [Name], [Typst],\n  [Pronunciation], ipa,\n)\n
\"Preview\"
\n

In the example, you can see that the variable can be used both in markup\n(prefixed with a #) and in a function call (by just typing its name). Of\ncourse, we can change the value of the variable and all its occurrences will\nautomatically change with it. Let's make it a bit clearer what is IPA and what\nis normal prose by rendering IPA in italics. We are also using slashes which, by\nconvention, often enclose IPA.

\n
#let ipa = text(\n  style: "italic",\n)[/taɪpst/]\n\nThe canonical way to\npronounce Typst is #ipa.\n\n#table(\n  columns: (1fr, 1fr),\n  [Name], [Typst],\n  [Pronunciation], ipa,\n)\n
\"Preview\"
\n

Here, we called the text function and assigned its return value to the\nvariable. When you call a function, it processes its arguments and then yields\nanother value (often content). So far in this tutorial, we called most\nfunctions directly in markup, like this: #text(fill: red)[CRIMSON!]. This\ncall to the text function returns the red text as a return value. Because we\nplaced it in markup, its return value just immediately got inserted into the\ncontent we wrote. With variables, we can instead store it to use it later or\ncompose it with other values.

\n

Variables are not limited to storing content: they can store any data type Typst\nknows about. Throughout this tutorial, you made use of many data types when you\npassed them to Typst's built-in functions. Here is an example assigning each of\nthem to a variable:

\n
// Content with markup inside\n#let blind-text = [_Lorem ipsum_ dolor sit amet]\n\n// Unformatted strings\n#let funny-font = "MS Comic Sans"\n\n// Absolute lengths (see also pt, in, ...)\n#let mile = 160934cm\n\n// Lengths relative to the font size\n#let double-space = 2em\n\n// Ratios\n#let progress = 80%\n\n// Integer numbers\n#let answer = 42\n\n// Booleans\n#let truth = false\n\n// Horizontal and vertical alignment\n#let focus = center\n
\n

In this chapter of the tutorial, you will leverage variables and your own\nfunctions to build templates that can be reused across multiple documents.

\n

A toy template

\n

In Typst, templates are functions in which you can wrap your whole document. To\nlearn how to do that, let's first review how to write your very own functions.\nThey can do anything you want them to, so why not go a bit crazy?

\n
#let amazed(term) = box[✨ #term ✨]\n\nYou are #amazed[beautiful]!\n
\"Preview\"
\n

Comparing this against the previous section, you may have noticed that this\nlooks a lot like a variable definition using let. This instinct is correct:\nFunctions are just another data type. Here, we are defining the variable\namazed, assigning it a function that takes a single argument, term, and\nreturns content with the term surrounded by sparkles. We also put the whole\nthing in a box so that the term we are amazed by cannot be separated from\nits sparkles by a line break. The special function definition syntax makes the\ndefinition shorter and more readable, but you can also use the regular variable\ndefinition syntax (see the scripting reference for\ndetails). After its definition, we are able to call the function just like all\nbuilt-in functions.

\n

Many functions that come with Typst have optional named parameters. Our\nfunctions can also have them. Let's add a parameter to our function that lets us\nchoose the color of the text. We need to provide a default color in case the\nparameter isn't given.

\n
#let amazed(term, color: blue) = {\n  text(color, box[✨ #term ✨])\n}\n\nYou are #amazed[beautiful]!\nI am #amazed(color: purple)[amazed]!\n
\"Preview\"
\n

Templates now work by wrapping our whole document in a custom function like\namazed. But wrapping a whole document in a giant function call would be\ncumbersome! Instead, we can use an "everything" show rule to achieve the same\nwith cleaner code. To write such a show rule, put a colon directly after the\nshow keyword and then provide a function. This function is given the rest of the\ndocument as a parameter. The function can then do anything with this content.\nSince the amazed function can be called with a single content argument, we can\njust pass it by name to the show rule. Let's try it:

\n
#show: amazed\nI choose to focus on the good\nin my life and let go of any\nnegative thoughts or beliefs.\nIn fact, I am amazing!\n
\"Preview\"
\n

Our whole document will now be passed to the amazed function, as if we wrapped\nit around it. Of course, this is not especially useful with this particular\nfunction, but when combined with set rules and named arguments, it can be very\npowerful.

\n

Embedding set and show rules

\n

To apply some set and show rules to our template, we can use set and show\nwithin a content block in our function and then insert the document into\nthat content block.

\n
#let template(doc) = [\n  #set text(font: "Inria Serif")\n  #show "something cool": [Typst]\n  #doc\n]\n\n#show: template\nI am learning something cool today.\nIt's going great so far!\n
\"Preview\"
\n

Just like we already discovered in the previous chapter, set rules will apply to\neverything within their content block. Since the everything show rule passes our\nwhole document to the template function, the text set rule and string show\nrule in our template will apply to the whole document. Let's use this knowledge\nto create a template that reproduces the body style of the paper we wrote in the\nprevious chapter.

\n
#let conf(title, doc) = {\n  set page(\n    paper: "us-letter",\n    header: align(\n      right + horizon,\n      title\n    ),\n    columns: 2,\n    ...\n  )\n  set par(justify: true)\n  set text(\n    font: "Libertinus Serif",\n    size: 11pt,\n  )\n\n  // Heading show rules.\n  ...\n\n  doc\n}\n\n#show: doc => conf(\n  [Paper title],\n  doc,\n)\n\n= Introduction\n...\n
\"Preview\"
\n

We copy-pasted most of that code from the previous chapter. The two differences\nare this:

\n
    \n
  1. \n

    We wrapped everything in the function conf using an everything show rule.\nThe function applies a few set and show rules and echoes the content it has\nbeen passed at the end.

    \n
    2. \n
  2. \n

    Moreover, we used a curly-braced code block instead of a content block. This\nway, we don't need to prefix all set rules and function calls with a #. In\nexchange, we cannot write markup directly in the code block anymore.

    \n
    3. \n
\n

Also note where the title comes from: We previously had it inside of a variable.\nNow, we are receiving it as the first parameter of the template function. To do\nso, we passed a closure (that's a function without a name that is used right\naway) to the everything show rule. We did that because the conf function\nexpects two positional arguments, the title and the body, but the show rule will\nonly pass the body. Therefore, we add a new function definition that allows us\nto set a paper title and use the single parameter from the show rule.

\n

Templates with named arguments

\n

Our paper in the previous chapter had a title and an author list. Let's add\nthese things to our template. In addition to the title, we want our template to\naccept a list of authors with their affiliations and the paper's abstract. To\nkeep things readable, we'll add those as named arguments. In the end, we want it\nto work like this:

\n
#show: doc => conf(\n  title: [\n    A Fluid Dynamic Model for\n    Glacier Flow\n  ],\n  authors: (\n    (\n      name: "Theresa Tungsten",\n      affiliation: "Artos Institute",\n      email: "tung@artos.edu",\n    ),\n    (\n      name: "Eugene Deklan",\n      affiliation: "Honduras State",\n      email: "e.deklan@hstate.hn",\n    ),\n  ),\n  abstract: lorem(80),\n  doc,\n)\n\n...\n
\n

Let's build this new template function. First, we add a default value to the\ntitle argument. This way, we can call the template without specifying a title.\nWe also add the named authors and abstract parameters with empty defaults.\nNext, we copy the code that generates title, abstract and authors from the\nprevious chapter into the template, replacing the fixed details with the\nparameters.

\n

The new authors parameter expects an array of dictionaries\nwith the keys name, affiliation and email. Because we can have an\narbitrary number of authors, we dynamically determine if we need one, two or\nthree columns for the author list. First, we determine the number of authors\nusing the .len() method on the authors array. Then, we set the\nnumber of columns as the minimum of this count and three, so that we never\ncreate more than three columns. If there are more than three authors, a new row\nwill be inserted instead. For this purpose, we have also added a row-gutter\nparameter to the grid function. Otherwise, the rows would be too close\ntogether. To extract the details about the authors from the dictionary, we use\nthe field access syntax.

\n

We still have to provide an argument to the grid for each author: Here is where\nthe array's map method comes in handy. It takes a function as an\nargument that gets called with each item of the array. We pass it a function\nthat formats the details for each author and returns a new array containing\ncontent values. We've now got one array of values that we'd like to use as\nmultiple arguments for the grid. We can do that by using the\nspread operator. It takes an array and applies each of its items\nas a separate argument to the function.

\n

The resulting template function looks like this:

\n
#let conf(\n  authors: (),\n  abstract: [],\n  doc,\n) = {\n  // Set and show rules from before.\n  ...\n\n  place(\n    top + center,\n    float: true,\n    scope: "parent",\n    clearance: 2em,\n    {\n      title()\n\n      let count = authors.len()\n      let ncols = calc.min(count, 3)\n      grid(\n        columns: (1fr,) * ncols,\n        row-gutter: 24pt,\n        ..authors.map(author => [\n          #author.name \\\n          #author.affiliation \\\n          #link("mailto:" + author.email)\n        ]),\n      )\n\n      par(justify: false)[\n        *Abstract* \\\n        #abstract\n      ]\n\n    }\n  )\n\n  doc\n}\n
\n

A separate file

\n

Most of the time, a template is specified in a different file and then imported\ninto the document. This way, the main file you write in is kept clutter free and\nyour template is easily reused. Create a new text file in the file panel by\nclicking the plus button and name it conf.typ. Move the conf function\ndefinition inside of that new file. Now you can access it from your main file by\nadding an import before the show rule. Specify the path of the file between the\nimport keyword and a colon, then name the function that you want to import.

\n

Another thing that you can do to make applying templates just a bit more elegant\nis to use the .with method on functions to pre-populate all\nthe named arguments. This way, you can avoid spelling out a closure and\nappending the content argument at the bottom of your template list. Templates on\nTypst Universe are designed to work with this style of function\ncall.

\n
#import "conf.typ": conf\n\n#set document(title: [\n  A Fluid Dynamic Model for\n  Glacier Flow\n])\n\n#show: conf.with(\n  authors: (\n    (\n      name: "Theresa Tungsten",\n      affiliation: "Artos Institute",\n      email: "tung@artos.edu",\n    ),\n    (\n      name: "Eugene Deklan",\n      affiliation: "Honduras State",\n      email: "e.deklan@hstate.hn",\n    ),\n  ),\n  abstract: lorem(80),\n)\n\n= Introduction\n#lorem(90)\n\n== Motivation\n#lorem(140)\n\n== Problem Statement\n#lorem(50)\n\n= Related Work\n#lorem(200)\n
\"Preview\"
\n

We have now converted the conference paper into a reusable template for that\nconference! Why not share it in the Forum or on\nTypst's Discord server so that others can use\nit too?

\n

Review

\n

Congratulations, you have completed Typst's Tutorial! In this section, you have\nlearned how to define your own functions and how to create and apply templates\nthat define reusable document styles. You've made it far and learned a lot. You\ncan now use Typst to write your own documents and share them with others.

\n

We are still a super young project and are looking for feedback. If you have any\nquestions, suggestions or you found a bug, please let us know\nin the Forum,\non our Discord server,\non GitHub,\nor via the web app's feedback form (always available in the Help menu).

\n

So what are you waiting for? Sign up and write something!

"}}