4 files changed, 104 insertions, 52 deletions
diff --git a/docs/src/tutorial/1-writing.md b/docs/src/tutorial/1-writing.md
index 50ae699c..78c1bc14 100644
--- a/docs/src/tutorial/1-writing.md
+++ b/docs/src/tutorial/1-writing.md
@@ -55,9 +55,9 @@ items.
 + The geology
 ```
 
-If we wanted to add a bulleted list, we would use the `-` character instead of the
-`+` character. We can also nest lists: For example, we can add a sub-list to the
-first item of the list above by indenting it.
+If we wanted to add a bulleted list, we would use the `-` character instead of
+the `+` character. We can also nest lists: For example, we can add a sub-list to
+the first item of the list above by indenting it.
 
 ```example
 + The climate
@@ -67,7 +67,7 @@ first item of the list above by indenting it.
 + The geology
 ```
 
-## Adding images
+## Adding a figure
 You think that your report would benefit from a figure. Let's add one. Typst
 supports images in the formats PNG, JPEG, GIF, and SVG. To add an image file to
 your project, first open the _file panel_ by clicking the box icon in the left
@@ -83,9 +83,9 @@ We have seen before that specific symbols (called _markup_) have specific
 meaning in Typst. We can use `=`, `-`, `+`, and `_` to create headings, lists
 and emphasized text, respectively. However, having a special symbol for
 everything we want to insert into our document would soon become cryptic and
-unwieldy. For this reason, Typst reserves markup symbols only for the most common
-things. Everything else is inserted with _functions._ For our image to show up
-on the page, we use Typst's [`image`]($func/image) function.
+unwieldy. For this reason, Typst reserves markup symbols only for the most
+common things. Everything else is inserted with _functions._ For our image to
+show up on the page, we use Typst's [`image`]($func/image) function.
 
 ```example
 #image("glacier.jpg")
@@ -95,11 +95,11 @@ In general, a function produces some output for a set of _arguments_. When you
 _call_ a function within markup, you provide the arguments and Typst inserts the
 result (the function's _return value_) into the document. In our case, the
 `image` function takes one argument: The path to the image file. To call a
-function, we first need to type the `#` character, immediately followed by the
-name of the function. Then, we enclose the arguments in parentheses. Typst
-recognizes many different data types within argument lists. Our file path is a
-short [string of text]($type/string), so we need to enclose it
-in double quotes.
+function in markup, we first need to type the `#` character, immediately
+followed by the name of the function. Then, we enclose the arguments in
+parentheses. Typst recognizes many different data types within argument lists.
+Our file path is a short [string of text]($type/string), so we need to enclose
+it in double quotes.
 
 The inserted image uses the whole width of the page. To change that, pass the
 `width` argument to the `image` function. This is a _named_ argument and
@@ -110,40 +110,52 @@ they are separated by commas, so we first need to put a comma behind the path.
 #image("glacier.jpg", width: 70%)
 ```
 
-The `width` argument is a
-[relative length]($type/relative-length). In our case, we specified a
-percentage, determining that the image shall take up `{70%}` of the page's
-width. We also could have specified an absolute value like `{1cm}` or `{0.7in}`.
+The `width` argument is a [relative length]($type/relative-length). In our case,
+we specified a percentage, determining that the image shall take up `{70%}` of
+the page's width. We also could have specified an absolute value like `{1cm}` or
+`{0.7in}`.
 
-Just like text, the image is aligned at the left side of the page by default.
-That looks a bit awkward. Let's center it and add a caption. We achieve this by
-using the [`align`]($func/align) function. This function takes an `alignment` as
-its first argument and then the content that we want to align as the second
-argument:
+Just like text, the image is now aligned at the left side of the page by
+default. It's also lacking a caption. Let's fix that by using the
+[figure]($func/figure) function. This function takes the figure's contents as a
+positional argument and an optional caption as a named argument.
 
-```example
-#align(center)[
-  #image("glacier.jpg", width: 70%)
+Within the argument list of the `figure` function, Typst is already in code mode. This means, you can now remove the hashtag before the image function call.
+The hashtag is only needed directly in markup (to disambiguate text from function calls).
 
-  _Glaciers form an important
-   part of the earth's climate
-   system._
-]
-```
+The caption consists of arbitrary markup. To give markup to a function, we
+enclose it in square brackets. This construct is called a _content block._
 
-Did you spot the closing bracket `]` at the end of the example? Both the
-argument and the caption are enclosed in the same square brackets. Therefore,
-the `align` function centers both of them.
+```example
+#figure(
+  image("glacier.jpg", width: 70%),
+  caption: [
+    _Glaciers_ form an important part
+    of the earth's climate system.
+  ],
+)
+```
 
-But wait, shouldn't the arguments of a function be specified within parentheses?
-Why is there a second set of square brackets with the aligned content after the
-parentheses?
+You continue to write your report and now want to reference the figure. To do
+that, first attach a label to figure. A label uniquely identifies an element in
+your document. Add one after the figure by enclosing some name in angle
+brackets. You can then reference the figure in your text by writing an `[@]`
+symbol followed by that name. Headings and equations can also be labelled to
+make them referencable.
 
-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. We call markup in square brackets
-a _content block._
+```example
+Glaciers as the one shown in
+@glaciers will cease to exist if
+we don't take action soon!
+
+#figure(
+  image("glacier.jpg", width: 70%),
+  caption: [
+    _Glaciers_ form an important part
+    of the earth's climate system.
+  ],
+) <glaciers>
+```
 
 <div class="info-box">
 
@@ -159,11 +171,37 @@ 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 a another image as
 the image's path parameter. That's why only strings are allowed here.
 On the contrary, strings work wherever content is expected because text is a
-kind of valid content.
+valid kind of content.
 </div>
 
+## Adding a 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`]($func/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 final 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]($func/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 introduction, you move on to the meat of the document:
+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:
@@ -194,8 +232,8 @@ 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:
+The flow rate of a glacier is given
+by the following equation:
 
 $ Q = rho A v + "time offset" $
 ```
diff --git a/docs/src/tutorial/2-formatting.md b/docs/src/tutorial/2-formatting.md
index ed166db0..d5b810b2 100644
--- a/docs/src/tutorial/2-formatting.md
+++ b/docs/src/tutorial/2-formatting.md
@@ -31,6 +31,13 @@ complete document in it.
 ]
 ```
 
+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. The [`par`]($func/par) function justifies all
 paragraphs within it. However, wrapping the document in countless functions and
 applying styles selectively and in-situ can quickly become cumbersome.
@@ -100,9 +107,12 @@ 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 text(font: "New Computer Modern", 10pt)
+#set text(
+  font: "New Computer Modern",
+  size: 10pt
+)
 #set page(
-  "a6",
+  paper: "a6",
   margin: (x: 1.8cm, y: 1.5cm),
 )
 #set par(
diff --git a/docs/src/tutorial/3-advanced.md b/docs/src/tutorial/3-advanced.md
index 7d6bccf6..1a580ece 100644
--- a/docs/src/tutorial/3-advanced.md
+++ b/docs/src/tutorial/3-advanced.md
@@ -50,9 +50,6 @@ to learn some new tricks.
 Let's start by writing some set rules for the document.
 
 ```example
-#set text(font: "Linux Libertine", 11pt)
-#set par(justify: true)
-
 #set page(
 >>>  margin: auto,
   paper: "us-letter",
@@ -62,6 +59,11 @@ Let's start by writing some set rules for the document.
   ],
   numbering: "1",
 )
+#set par(justify: true)
+#set text(
+  font: "Linux Libertine",
+  size: 11pt,
+)
 
 #lorem(600)
 ```
diff --git a/docs/src/tutorial/4-template.md b/docs/src/tutorial/4-template.md
index 3208f012..bba902a1 100644
--- a/docs/src/tutorial/4-template.md
+++ b/docs/src/tutorial/4-template.md
@@ -86,8 +86,6 @@ previous chapter.
 
 ```example
 #let conf(title, doc) = {
-  set text(font: "Linux Libertine", 11pt)
-  set par(justify: true)
   set page(
     paper: "us-letter",
 >>> margin: auto,
@@ -97,6 +95,11 @@ previous chapter.
     ),
 <<<     ...
   )
+  set par(justify: true)
+  set text(
+    font: "Linux Libertine",
+    size: 11pt,
+  )
 
   // Heading show rules.
 <<<   ...
@@ -324,7 +327,6 @@ path of the file after the `{from}` keyword.
 >>>  columns(2, doc)
 >>>}
 <<< #import "conf.typ": conf
-
 #show: doc => conf(
   title: [
     Towards Improved Modelling