summaryrefslogtreecommitdiff
path: root/docs/guides
diff options
context:
space:
mode:
authorLaurenz <laurmaedje@gmail.com>2023-09-11 15:53:20 +0200
committerLaurenz <laurmaedje@gmail.com>2023-09-11 15:53:20 +0200
commit3a979e88da7be6240821ba8acfdd376b7f4e0f09 (patch)
treeb41a095a11d710f0fc5547e5bd0627deafa02af2 /docs/guides
parent305524d005df075d53575552ee090fb53192a3fe (diff)
Docs generation for types
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/guide-for-latex-users.md201
-rw-r--r--docs/guides/page-setup.md177
-rw-r--r--docs/guides/welcome.md2
3 files changed, 188 insertions, 192 deletions
diff --git a/docs/guides/guide-for-latex-users.md b/docs/guides/guide-for-latex-users.md
index b51e8cf1..73673523 100644
--- a/docs/guides/guide-for-latex-users.md
+++ b/docs/guides/guide-for-latex-users.md
@@ -4,7 +4,7 @@ description: |
similarities between Typst and LaTeX so you can get started quickly.
---
-# Guide for LaTeX users
+# Guide for LaTeX users { # }
This page is a good starting point if you have used LaTeX before and want to try
out Typst. We will explore the main differences between these two systems from a
user perspective. Although Typst is not built upon LaTeX and has a different
@@ -32,8 +32,8 @@ That's easy. You just create a new, empty text file (the file extension is
`.typ`). No boilerplate is needed to get started. Simply start by writing your
text. It will be set on an empty A4-sized page. If you are using the web app,
click "+ Empty document" to create a new project with a file and enter the
-editor. [Paragraph breaks]($func/parbreak) work just as they do in LaTeX, just
-use a blank line.
+editor. [Paragraph breaks]($parbreak) work just as they do in LaTeX, just use a
+blank line.
```example
Hey there!
@@ -47,8 +47,8 @@ LaTeX uses the command `\section` to create a section heading. Nested headings
are indicated with `\subsection`, `\subsubsection`, etc. Depending on your
document class, there is also `\part` or `\chapter`.
-In Typst, [headings]($func/heading) are less verbose: You prefix the line with
-the heading on it with an equals sign and a space to get a first-order heading:
+In Typst, [headings]($heading) are less verbose: You prefix the line with the
+heading on it with an equals sign and a space to get a first-order heading:
`[= Introduction]`. If you need a second-order heading, you use two equals
signs: `[== In this paper]`. You can nest headings as deeply as you'd like by
adding more equals signs.
@@ -60,23 +60,23 @@ Emphasis (usually rendered as italic text) is expressed by enclosing text in
Here is a list of common markup commands used in LaTeX and their Typst
equivalents. You can also check out the [full syntax cheat sheet]($syntax).
-| Element | LaTeX | Typst | See |
-|:-----------------|:--------------------------|:-----------------------|:-------------------------|
-| Strong emphasis | `\textbf{strong}` | `[*strong*]` | [`strong`]($func/strong) |
-| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`]($func/emph) |
-| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`]($func/raw) |
-| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]($func/link) |
-| Label | `\label{intro}` | `[<intro>]` | [`label`]($func/label) |
-| Reference | `\ref{intro}` | `[@intro]` | [`ref`]($func/ref) |
-| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`]($func/cite) |
-| Bullet list | `itemize` environment | `[- List]` | [`list`]($func/list) |
-| Numbered list | `enumerate` environment | `[+ List]` | [`enum`]($func/enum) |
-| Term list | `description` environment | `[/ Term: List]` | [`terms`]($func/terms) |
-| Figure | `figure` environment | `figure` function | [`figure`]($func/figure) |
-| Table | `table` environment | `table` function | [`table`]($func/table) |
-| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($func/math.equation) |
-
-[Lists]($func/list) do not rely on environments in Typst. Instead, they have
+| Element | LaTeX | Typst | See
+|:-----------------|:--------------------------|:-----------------------|:--------------------
+| Strong emphasis | `\textbf{strong}` | `[*strong*]` | [`strong`]($strong) |
+| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`]($emph) |
+| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`]($raw) |
+| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]($link) |
+| Label | `\label{intro}` | `[<intro>]` | [`label`]($label) |
+| Reference | `\ref{intro}` | `[@intro]` | [`ref`]($ref) |
+| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`]($cite) |
+| Bullet list | `itemize` environment | `[- List]` | [`list`]($list) |
+| Numbered list | `enumerate` environment | `[+ List]` | [`enum`]($enum) |
+| Term list | `description` environment | `[/ Term: List]` | [`terms`]($terms) |
+| Figure | `figure` environment | `figure` function | [`figure`]($figure) |
+| Table | `table` environment | `table` function | [`table`]($table) |
+| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($math.equation) |
+
+[Lists]($list) do not rely on environments in Typst. Instead, they have
lightweight syntax like headings. To create an unordered list (`itemize`),
prefix each line of an item with a hyphen:
@@ -100,11 +100,11 @@ To write this list in Typst...
````
Nesting lists works just by using proper indentation. Adding a blank line in
-between items results in a more [widely]($func/list.tight) spaced list.
+between items results in a more [widely]($list.tight) spaced list.
-To get a [numbered list]($func/enum) (`enumerate`) instead, use a `+` instead of
-the hyphen. For a [term list]($func/terms) (`description`), write
-`[/ Term: Description]` instead.
+To get a [numbered list]($enum) (`enumerate`) instead, use a `+` instead of the
+hyphen. For a [term list]($terms) (`description`), write `[/ Term: Description]`
+instead.
## How do I use a command? { #commands }
LaTeX heavily relies on commands (prefixed by backslashes). It uses these
@@ -115,16 +115,16 @@ braces: `\cite{rasmus}`.
Typst differentiates between [markup mode and code mode]($scripting/#blocks).
The default is markup mode, where you compose text and apply syntactic
constructs such as `[*stars for bold text*]`. Code mode, on the other hand,
-parallels programming languages like Python, providing the option to input
-and execute segments of code.
+parallels programming languages like Python, providing the option to input and
+execute segments of code.
Within Typst's markup, you can switch to code mode for a single command (or
rather, _expression_) using a hashtag (`#`). This is how you call functions to,
-for example, split your project into different [files]($scripting/#modules)
-or render text based on some [condition]($scripting/#conditionals).
-Within code mode, it is possible to include normal markup
-[_content_]($type/content) by using square brackets. Within code mode, this
-content is treated just as any other normal value for a variable.
+for example, split your project into different [files]($scripting/#modules) or
+render text based on some [condition]($scripting/#conditionals). Within code
+mode, it is possible to include normal markup [_content_]($content) by using
+square brackets. Within code mode, this content is treated just as any other
+normal value for a variable.
```example
First, a rectangle:
@@ -142,15 +142,14 @@ And finally a little loop:
]
```
-A function call always involves the name of the function ([`rect`]($func/rect),
-[`underline`]($func/underline), [`calc.max`]($func/calc.max),
-[`range`]($func/range)) followed by parentheses (as opposed to LaTeX where the
-square brackets and curly braces are optional if the macro requires no
-arguments). The expected list of arguments passed within those parentheses
-depends on the concrete function and is specified in the
-[reference]($reference).
+A function call always involves the name of the function ([`rect`]($rect),
+[`underline`]($underline), [`calc.max`]($calc.max), [`range`]($range)) followed
+by parentheses (as opposed to LaTeX where the square brackets and curly braces
+are optional if the macro requires no arguments). The expected list of arguments
+passed within those parentheses depends on the concrete function and is
+specified in the [reference]($reference).
-### Arguments { #arguments }
+### Arguments
A function can have multiple arguments. Some arguments are positional, i.e., you
just provide the value: The function `[#lower("SCREAM")]` returns its argument
in all-lowercase. Many functions use named arguments instead of positional
@@ -173,13 +172,13 @@ Named arguments are similar to how some LaTeX environments are configured, for
example, you would type `\begin{enumerate}[label={\alph*)}]` to start a list
with the labels `a)`, `b)`, and so on.
-Often, you want to provide some [content]($type/content) to a function. For
-example, the LaTeX command `\underline{Alternative A}` would translate to
+Often, you want to provide some [content]($content) to a function. For example,
+the LaTeX command `\underline{Alternative A}` would translate to
`[#underline([Alternative A])]` in Typst. The square brackets indicate that a
-value is [content]($type/content). Within these brackets, you can use normal
-markup. However, that's a lot of parentheses for a pretty simple construct.
-This is why you can also move trailing content arguments after the parentheses
-(and omit the parentheses if they would end up empty).
+value is [content]($content). Within these brackets, you can use normal markup.
+However, that's a lot of parentheses for a pretty simple construct. This is why
+you can also move trailing content arguments after the parentheses (and omit the
+parentheses if they would end up empty).
```example
Typst is an #underline[alternative]
@@ -188,20 +187,20 @@ to LaTeX.
#rect(fill: aqua)[Get started here!]
```
-### Data types { #data-types }
+### Data types
You likely already noticed that the arguments have distinctive data types. Typst
-supports [many data types]($type). Below, there is a table with some of the most
+supports many data types. Below, there is a table with some of the most
important ones and how to write them. In order to specify values of any of these
types, you have to be in code mode!
-| Data type | Example |
-|:-------------------------------------|:----------------------------------|
-| [Content]($type/content) | `{[*fast* typesetting]}` |
-| [String]($type/string) | `{"Pietro S. Author"}` |
-| [Integer]($type/integer) | `{23}` |
-| [Floating point number]($type/float) | `{1.459}` |
-| [Absolute length]($type/length) | `{12pt}`, `{5in}`, `{0.3cm}`, ... |
-| [Relative length]($type/ratio) | `{65%}` |
+| Data type | Example |
+|:--------------------------------|:----------------------------------|
+| [Content]($content) | `{[*fast* typesetting]}` |
+| [String]($str) | `{"Pietro S. Author"}` |
+| [Integer]($int) | `{23}` |
+| [Floating point number]($float) | `{1.459}` |
+| [Absolute length]($length) | `{12pt}`, `{5in}`, `{0.3cm}`, ... |
+| [Relative length]($ratio) | `{65%}` |
The difference between content and string is that content can contain markup,
including function calls, while a string really is just a plain sequence of
@@ -219,9 +218,9 @@ braces and only affect that argument. Other commands such as
content within the document or current scope.
In Typst, the same function can be used both to affect the appearance for the
-remainder of the document, a block (or scope), or just its arguments. For example,
-`[#text(weight: "bold")[bold text]]` will only embolden its argument, while
-`[#set text(weight: "bold")]` will embolden any text until the end of the
+remainder of the document, a block (or scope), or just its arguments. For
+example, `[#text(weight: "bold")[bold text]]` will only embolden its argument,
+while `[#set text(weight: "bold")]` will embolden any text until the end of the
current block, or, if there is none, document. The effects of a function are
immediately obvious based on whether it is used in a call or a
[set rule.]($styling/#set-rules)
@@ -249,9 +248,9 @@ Good results can only be obtained by
```
The `+` is syntactic sugar (think of it as an abbreviation) for a call to the
-[`{enum}`]($func/enum) function, to which we apply a set rule above. [Most
-syntax is linked to a function in this way.]($syntax) If you need to style an
-element beyond what its arguments enable, you can completely redefine its
+[`{enum}`]($enum) function, to which we apply a set rule above.
+[Most syntax is linked to a function in this way.]($syntax) If you need to style
+an element beyond what its arguments enable, you can completely redefine its
appearance with a [show rule]($styling/#show-rules) (somewhat comparable to
`\renewcommand`).
@@ -261,7 +260,7 @@ command to define how your document is supposed to look. In that command, you
may have replaced `article` with another value such as `report` and `amsart` to
select a different look.
-When using Typst, you style your documents with [functions]($type/function).
+When using Typst, you style your documents with [functions]($function).
Typically, you use a template that provides a function that styles your whole
document. First, you import the function from a template file. Then, you apply
it to your whole document. This is accomplished with a
@@ -357,7 +356,7 @@ paragraphs right here!
```
The [`{import}`]($scripting/#modules) statement makes
-[functions]($type/function) (and other definitions) from another file available.
+[functions]($function) (and other definitions) from another file available.
In this example, it imports the `conf` function from the `conf.typ` file. This
function formats a document as a conference article. We use a show rule to apply
it to the document and also configure some metadata of the article. After
@@ -393,23 +392,23 @@ Typst is "batteries included," so the equivalent of many popular LaTeX packages
is built right-in. Below, we compiled a table with frequently loaded packages
and their corresponding Typst functions.
-| LaTeX Package | Typst Alternative |
-|:--------------------------------|:---------------------------------------------------------------------|
-| graphicx, svg | [`image`]($func/image) function |
-| tabularx | [`table`]($func/table), [`grid`]($func/grid) functions |
-| fontenc, inputenc, unicode-math | Just start writing! |
-| babel, polyglossia | [`text`]($func/text.lang) function: `[#set text(lang: "zh")]` |
-| amsmath | [Math mode]($category/math) |
-| amsfonts, amssymb | [`sym`]($category/symbols) module and [syntax]($syntax/#math) |
-| geometry, fancyhdr | [`page`]($func/page) function |
-| xcolor | [`text`]($func/text.fill) function: `[#set text(fill: rgb("#0178A4"))]` |
-| hyperref | [`link`]($func/link) function |
-| bibtex, biblatex, natbib | [`cite`]($func/cite), [`bibliography`]($func/bibliography) functions |
-| lstlisting, minted | [`raw`]($func/raw) function and syntax |
-| parskip | [`block`]($func/block.spacing) and [`par`]($func/par.first-line-indent) functions |
-| csquotes | Set the [`text`]($func/text.lang) language and type `["]` or `[']` |
-| caption | [`figure`]($func/figure) function |
-| enumitem | [`list`]($func/list), [`enum`]($func/enum), [`terms`]($func/terms) functions |
+| LaTeX Package | Typst Alternative |
+|:--------------------------------|:------------------------------------------------------------- |
+| graphicx, svg | [`image`]($image) function |
+| tabularx | [`table`]($table), [`grid`]($grid) functions |
+| fontenc, inputenc, unicode-math | Just start writing! |
+| babel, polyglossia | [`text`]($text.lang) function: `[#set text(lang: "zh")]` |
+| amsmath | [Math mode]($category/math) |
+| amsfonts, amssymb | [`sym`]($category/symbols) module and [syntax]($syntax/#math) |
+| geometry, fancyhdr | [`page`]($page) function |
+| xcolor | [`text`]($text.fill) function: `[#set text(fill: rgb("#0178A4"))]` |
+| hyperref | [`link`]($link) function |
+| bibtex, biblatex, natbib | [`cite`]($cite), [`bibliography`]($bibliography) functions |
+| lstlisting, minted | [`raw`]($raw) function and syntax |
+| parskip | [`block`]($block.spacing) and [`par`]($par.first-line-indent) functions |
+| csquotes | Set the [`text`]($text.lang) language and type `["]` or `[']` |
+| caption | [`figure`]($figure) function |
+| enumitem | [`list`]($list), [`enum`]($enum), [`terms`]($terms) functions |
If you need to load functions and variables from another file, for example, to
use a template, you can use an [`import`]($scripting/#modules) statement. If you
@@ -444,12 +443,12 @@ Typst pre-defines a lot of useful variables in math mode. All Greek (`alpha`,
their name. Some symbols are additionally available through shorthands, such as
`<=`, `>=`, and `->`.
-Refer to the [symbol page]($func/symbol) for a full list of the symbols.
+Refer to the [symbol pages]($reference/symbols) for a full list of the symbols.
If a symbol is missing, you can also access it through a
[Unicode escape sequence]($syntax/#escapes).
Alternate and related forms of symbols can often be selected by
-[appending a modifier]($type/symbol) after a period. For example,
+[appending a modifier]($symbol) after a period. For example,
`arrow.l.squiggly` inserts a squiggly left-pointing arrow. If you want to insert
multiletter text in your expression instead, enclose it in double quotes:
@@ -459,7 +458,7 @@ $ delta "if" x <= 5 $
In Typst, delimiters will scale automatically for their expressions, just as if
`\left` and `\right` commands were implicitly inserted in LaTeX. You can
-customize delimiter behavior using the [`lr` function]($func/math.lr). To
+customize delimiter behavior using the [`lr` function]($math.lr). To
prevent a pair of delimiters from scaling, you can escape them with backslashes.
Typst will automatically set terms around a slash `/` as a fraction while
@@ -470,7 +469,7 @@ fraction will appear in the output.
$ f(x) = (x + 1) / x $
```
-[Sub- and superscripts]($func/math.attach) work similarly in Typst and LaTeX.
+[Sub- and superscripts]($math.attach) work similarly in Typst and LaTeX.
`{$x^2$}` will produce a superscript, `{$x_2$}` yields a subscript. If you want
to include more than one value in a sub- or superscript, enclose their contents
in parentheses: `{$x_(a -> epsilon)$}`.
@@ -487,7 +486,7 @@ $ f(x, y) := cases(
) $
```
-The above example uses the [`cases` function]($func/math.cases) to describe f. Within
+The above example uses the [`cases` function]($math.cases) to describe f. Within
the cases function, arguments are delimited using commas and the arguments are
also interpreted as math. If you need to interpret arguments as Typst
values instead, prefix them with a `#`:
@@ -514,7 +513,7 @@ If you'd like to enter your mathematical symbols directly as Unicode, that is
possible, too!
Math calls can have two-dimensional argument lists using `;` as a delimiter. The
-most common use for this is the [`mat` function]($func/math.mat) that creates
+most common use for this is the [`mat` function]($math.mat) that creates
matrices:
```example
@@ -531,13 +530,13 @@ Papers set in LaTeX have an unmistakeable look. This is mostly due to their
font, Computer Modern, justification, narrow line spacing, and wide margins.
The example below
-- sets wide [margins]($func/page.margin)
-- enables [justification]($func/par.justify), [tighter lines]($func/par.leading)
- and [first-line-indent]($func/par.first-line-indent)
-- [sets the font]($func/text.font) to "New Computer Modern", an OpenType
- derivate of Computer Modern for both text and [code blocks]($func/raw)
-- disables paragraph [spacing]($func/block.spacing)
-- increases [spacing]($func/block.spacing) around [headings]($func/heading)
+- sets wide [margins]($page.margin)
+- enables [justification]($par.justify), [tighter lines]($par.leading) and
+ [first-line-indent]($par.first-line-indent)
+- [sets the font]($text.font) to "New Computer Modern", an OpenType derivate of
+ Computer Modern for both text and [code blocks]($raw)
+- disables paragraph [spacing]($block.spacing)
+- increases [spacing]($block.spacing) around [headings]($heading)
```typ
#set page(margin: 1.75in)
@@ -566,9 +565,9 @@ applicable, contains possible workarounds.
- **Change page margins without a pagebreak.** In LaTeX, margins can always be
adjusted, even without a pagebreak. To change margins in Typst, you use the
- [`page` function]($func/page) which will force a page break. If you just want
- a few paragraphs to stretch into the margins, then reverting to the old
- margins, you can use the [`pad` function]($func/pad) with negative padding.
+ [`page` function]($page) which will force a page break. If you just want a few
+ paragraphs to stretch into the margins, then reverting to the old margins, you
+ can use the [`pad` function]($pad) with negative padding.
- **Floating figures.** The figure command of LaTeX will smartly choose where to
place a figure, be it on the top or bottom of the page, or a dedicated figure
@@ -589,9 +588,9 @@ applicable, contains possible workarounds.
orphans, it uses less sophisticated algorithms to determine page breaks. You
can insert custom page breaks in Typst using `[#pagebreak(weak: true)]` before
submitting your document. The argument `weak` ensures that no double page
- break will be created if this spot would be a natural page break
- anyways. You can also use `[#v(1fr)]` to distribute space on your page. It
- works quite similar to LaTeX's `\vfill`.
+ break will be created if this spot would be a natural page break anyways. You
+ can also use `[#v(1fr)]` to distribute space on your page. It works quite
+ similar to LaTeX's `\vfill`.
- **Bibliographies are not customizable.** In LaTeX, the packages `bibtex`,
`biblatex`, and `natbib` provide a wide range of reference and bibliography
diff --git a/docs/guides/page-setup.md b/docs/guides/page-setup.md
index b396a383..b3a2f801 100644
--- a/docs/guides/page-setup.md
+++ b/docs/guides/page-setup.md
@@ -16,28 +16,29 @@ you can get started with writing.
In Typst, each page has a width, a height, and margins on all four sides. The
top and bottom margins may contain a header and footer. The set rule of the
-[`{page}`]($func/page) element is where you control all of the page setup. If
-you make changes with this set rule, Typst will ensure that there is a new and
-conforming empty page afterward, so it may insert a page break. Therefore, it
-is best to specify your [`{page}`]($func/page) set rule at the start of your
-document or in your template.
+[`{page}`]($page) element is where you control all of the page setup. If you
+make changes with this set rule, Typst will ensure that there is a new and
+conforming empty page afterward, so it may insert a page break. Therefore, it is
+best to specify your [`{page}`]($page) set rule at the start of your document or
+in your template.
```example
#set rect(
width: 100%,
height: 100%,
- inset: 4pt
+ inset: 4pt,
)
>>> #set text(6pt)
+>>> #set page(margin: auto)
#set page(
- "iso-b7",
- header: rect[Header],
- footer: rect[Footer],
+ paper: "iso-b7",
+ header: rect(fill: aqua)[Header],
+ footer: rect(fill: aqua)[Footer],
number-align: center,
)
-#rect(fill: rgb("#565565"))
+#rect(fill: aqua)
```
This example visualizes the dimensions for page content, headers, and footers.
@@ -45,45 +46,46 @@ The page content is the page size (ISO B7) minus each side's default margin. In
the top and the bottom margin, there are stroked rectangles visualizing the
header and footer. They do not touch the main content, instead, they are offset
by 30% of the respective margin. You can control this offset by specifying the
-[`header-ascent`]($func/page.header-ascent) and
-[`footer-descent`]($func/page.footer-descent) arguments.
+[`header-ascent`]($page.header-ascent) and
+[`footer-descent`]($page.footer-descent) arguments.
Below, the guide will go more into detail on how to accomplish common page setup
requirements with examples.
## Customize page size and margins { #customize-margins }
-Typst's default page size is A4 paper. Depending on your region and your
-use case, you will want to change this. You can do this by using the
-[`{page}`]($func/page) set rule and passing it a string argument to use a common
-page size. Options include the complete ISO 216 series (e.g. `"iso-a4"`,
-`"iso-c2"`), customary US formats like `"us-legal"` or `"us-letter"`, and more.
-Check out the reference for the [page's paper argument]($func/page.paper) to
-learn about all available options.
+Typst's default page size is A4 paper. Depending on your region and your use
+case, you will want to change this. You can do this by using the
+[`{page}`]($page) set rule and passing it a string argument to use a common page
+size. Options include the complete ISO 216 series (e.g. `"iso-a4"`, `"iso-c2"`),
+customary US formats like `"us-legal"` or `"us-letter"`, and more. Check out the
+reference for the [page's paper argument]($page.paper) to learn about all
+available options.
```example
+>>> #set page(margin: auto)
#set page("us-letter")
This page likes freedom.
```
If you need to customize your page size to some dimensions, you can specify the
-named arguments [`width`]($func/page.width) and [`height`]($func/page.height)
-instead.
+named arguments [`width`]($page.width) and [`height`]($page.height) instead.
```example
+>>> #set page(margin: auto)
#set page(width: 12cm, height: 12cm)
This page is a square.
```
### Change the page's margins { #change-margins }
-Margins are a vital ingredient for good typography: [Typographers consider lines
-that fit between 45 and 75 characters best length for
-legibility](http://webtypography.net/2.1.2) and your margins and
+Margins are a vital ingredient for good typography:
+[Typographers consider lines that fit between 45 and 75 characters best length
+for legibility](http://webtypography.net/2.1.2) and your margins and
[columns](#columns) help define line widths. By default, Typst will create
margins proportional to the page size of your document. To set custom margins,
-you will use the [`margin`]($func/page.margin) argument in the
-[`{page}`]($func/page) set rule.
+you will use the [`margin`]($page.margin) argument in the [`{page}`]($page) set
+rule.
The `margin` argument will accept a length if you want to set all margins to the
same width. However, you often want to set different margins on each side. To do
@@ -119,11 +121,7 @@ the margin dictionary. The `inside` margin points towards the spine, and the
`outside` margin points towards the edge of the bound book.
```typ
-#set page(margin: (
- inside: 2.5cm,
- outside: 2cm,
- y: 1.75cm,
-))
+#set page(margin: (inside: 2.5cm, outside: 2cm, y: 1.75cm))
```
Typst will assume that documents written in Left-to-Right scripts are bound on
@@ -133,13 +131,12 @@ output by a different app, the binding is reversed from Typst's perspective.
Also, some books, like English-language Mangas are customarily bound on the
right, despite English using Left-to-Right script. To change the binding side
and explicitly set where the `inside` and `outside` are, set the
-[`binding`]($func/page.binding) argument in the [`{page}`]($func/page) set rule.
+[`binding`]($page.binding) argument in the [`{page}`]($page) set rule.
```typ
-#set text(lang: "es")
-
// Produce a book bound on the right,
// even though it is set in Spanish.
+#set text(lang: "es")
#set page(binding: right)
```
@@ -151,9 +148,9 @@ Headers and footers are inserted in the top and bottom margins of every page.
You can add custom headers and footers or just insert a page number.
In case you need more than just a page number, the best way to insert a header
-and a footer are the [`header`]($func/page.header) and
-[`footer`]($func/page.footer) arguments of the [`{page}`]($func/page) set rule.
-You can pass any content as their values:
+and a footer are the [`header`]($page.header) and [`footer`]($page.footer)
+arguments of the [`{page}`]($page) set rule. You can pass any content as their
+values:
```example
>>> #set page("a5", margin: (x: 2.5cm, y: 3cm))
@@ -168,7 +165,7 @@ You can pass any content as their values:
Headers are bottom-aligned by default so that they do not collide with the top
edge of the page. You can change this by wrapping your header in the
-[`{align}`]($func/align) function.
+[`{align}`]($align) function.
### Different header and footer on specific pages { #specific-pages }
You'll need different headers and footers on some pages. For example, you may
@@ -191,13 +188,13 @@ conditionally remove the header on the first page:
```
This example may look intimidating, but let's break it down: We are telling
-Typst that the header depends on the current [location]($func/locate). The `loc`
+Typst that the header depends on the current [location]($locate). The `loc`
value allows other functions to find out where on the page we currently are. We
-then ask Typst if the page [counter]($func/counter) is larger than one at our
-current position. The page counter starts at one, so we are skipping the header
-on a single page. Counters may have multiple levels. This feature is used for
-items like headings, but the page counter will always have a single level, so we
-can just look at the first one.
+then ask Typst if the page [counter]($counter) is larger than one at our current
+position. The page counter starts at one, so we are skipping the header on a
+single page. Counters may have multiple levels. This feature is used for items
+like headings, but the page counter will always have a single level, so we can
+just look at the first one.
You can, of course, add an `else` to this example to add a different header to
the first page instead.
@@ -206,8 +203,8 @@ the first page instead.
The technique described in the previous section can be adapted to perform more
advanced tasks using Typst's labels. For example, pages with big tables could
omit their headers to help keep clutter down. We will mark our tables with a
-`<big-table>` [label]($type/label) and use the [query system]($func/query) to
-find out if such a label exists on the current page:
+`<big-table>` [label]($label) and use the [query system]($query) to find out if
+such a label exists on the current page:
```typ
>>> #set page("a5", margin: (x: 2.5cm, y: 3cm))
@@ -232,8 +229,10 @@ find out if such a label exists on the current page:
#pagebreak()
#table(
- columns: 2 * (1fr, )
-)[A][B][C][D] <big-table>
+ columns: 2 * (1fr,),
+ [A], [B],
+ [C], [D],
+) <big-table>
```
Here, we query for all instances of the `<big-table>` label. We then check that
@@ -243,10 +242,10 @@ could add an `else` to add another header instead of deleting it.
## Add and customize page numbers { #page-numbers }
Page numbers help readers keep track of and reference your document more easily.
-The simplest way to insert footnotes is the [`numbering`]($func/page.numbering)
-argument of the [`{page}`]($func/page) set rule. You can pass a [_numbering
-pattern_]($func/numbering.numbering) string that shows how you want your pages
-to be numbered.
+The simplest way to insert footnotes is the [`numbering`]($page.numbering)
+argument of the [`{page}`]($page) set rule. You can pass a [_numbering
+pattern_]($numbering.numbering) string that shows how you want your pages to be
+numbered.
```example
>>> #set page("iso-b6", margin: 1.75cm)
@@ -278,21 +277,21 @@ the string.
This is one of many numbered pages.
```
-Go to the [`{numbering}` function reference]($func/numbering.numbering) to learn
-more about the arguments you can pass here.
+Go to the [`{numbering}` function reference]($numbering.numbering) to learn more
+about the arguments you can pass here.
In case you need to right- or left-align the page number, use the
-[`number-align`]($func/page.number-align) argument of the [`{page}`]($func/page)
-set rule. Alternating alignment between even and odd pages is not currently
-supported using this property. To do this, you'll need to specify a custom
-footer with your footnote and query the page counter as described in the section
-on conditionally omitting headers and footers.
+[`number-align`]($page.number-align) argument of the [`{page}`]($page) set rule.
+Alternating alignment between even and odd pages is not currently supported
+using this property. To do this, you'll need to specify a custom footer with
+your footnote and query the page counter as described in the section on
+conditionally omitting headers and footers.
-### Custom footer with page numbers { #custom-footer-with-page-numbers }
+### Custom footer with page numbers
Sometimes, you need to add other content than a page number to your footer.
-However, once a footer is specified, the [`numbering`]($func/page.numbering)
-argument of the [`{page}`]($func/page) set rule is ignored. This section shows
-you how to add a custom footer with page numbers and more.
+However, once a footer is specified, the [`numbering`]($page.numbering) argument
+of the [`{page}`]($page) set rule is ignored. This section shows you how to add
+a custom footer with page numbers and more.
```example
>>> #set page("iso-b6", margin: 1.75cm)
@@ -319,7 +318,7 @@ This page has a custom footer.
The example above shows how to add a custom footer with page numbers. First, we
need to recover the page number using the page counter. For this, we are using
-the [`{locate}` function]($func/locate) to check the page counter, just like in
+the [`{locate}` function]($locate) to check the page counter, just like in
the conditional header section. We then store the current and final page number
in variables.
@@ -328,8 +327,8 @@ insert all the free space on the line, and finally display the current page
number and the page total. This would work just the same in the header and with
any content.
-We can, of course, use the [`{numbering}` function]($func/numbering) to use
-numbering pattern strings like before:
+We can, of course, use the [`{numbering}` function]($numbering) to use numbering
+pattern strings like before:
```example
>>> #set page("iso-b6", margin: 1.75cm)
@@ -395,10 +394,10 @@ This page has a custom footer.
```
In this example, we use the number of pages to create an array of
-[circles]($func/circle). The circles are wrapped in a [box]($func/box) so they
-can all appear on the same line because they are blocks and would otherwise
-create paragraph breaks. The length of this [array]($type/array) depends on the
-current page number.
+[circles]($circle). The circles are wrapped in a [box]($box) so they can all
+appear on the same line because they are blocks and would otherwise create
+paragraph breaks. The length of this [array]($array) depends on the current page
+number.
We then insert the circles at the right side of the footer, with 1pt of space
between them. The join method of an array will attempt to
@@ -406,8 +405,8 @@ between them. The join method of an array will attempt to
value, interspersed with its argument. In our case, we get a single content
value with circles and spaces between them that we can use with the align
function. Finally, we use another box to ensure that the text and the circles
-can share a line and use the [`inset` argument]($func/box.inset) to raise the
-circles a bit so they line up nicely with the text.
+can share a line and use the [`inset` argument]($box.inset) to raise the circles
+a bit so they line up nicely with the text.
### Reset the page number and skip pages { #skip-pages }
Do you, at some point in your document, need to reset the page number? Maybe you
@@ -416,8 +415,7 @@ to skip a few page numbers because you will insert pages into the final printed
product.
The right way to modify the page number is to manipulate the page
-[counter]($func/counter). The simplest manipulation is to set the counter back
-to 1.
+[counter]($counter). The simplest manipulation is to set the counter back to 1.
```typ
#counter(page).update(1)
@@ -435,8 +433,8 @@ In this example, we skip five pages. `i` is the current value of the page
counter and `i + 5` is the return value of our function.
In case you need to retrieve the actual page number instead of the value of the
-page counter, you can use the [`page`]($func/locate) method on the argument of
-the `{locate}` closure:
+page counter, you can use the [`page`]($locate) method on the argument of the
+`{locate}` closure:
```example
#counter(page).update(i => i + 5)
@@ -447,7 +445,7 @@ the `{locate}` closure:
```
You can also obtain the page numbering pattern from the `{locate}` closure
-parameter with the [`page-numbering`]($func/locate) method.
+parameter with the [`page-numbering`]($locate) method.
## Add columns { #columns }
Add columns to your document to fit more on a page while maintaining legible
@@ -455,7 +453,7 @@ line lengths. Columns are vertical blocks of text which are separated by some
whitespace. This space is called the gutter.
If all of your content needs to be laid out in columns, you can just specify the
-desired number of columns in the [`{page}`]($func/page.columns) set rule:
+desired number of columns in the [`{page}`]($page.columns) set rule:
```example
>>> #set page(height: 120pt)
@@ -469,8 +467,8 @@ in the next section.
### Use columns anywhere in your document { #columns-anywhere }
Very commonly, scientific papers have a single-column title and abstract, while
the main body is set in two-columns. To achieve this effect, Typst includes a
-standalone [`{columns}` function]($func/columns) that can be used to insert
-columns anywhere on a page.
+standalone [`{columns}` function]($columns) that can be used to insert columns
+anywhere on a page.
Conceptually, the `columns` function must wrap the content of the columns:
@@ -502,8 +500,8 @@ nesting and write more legible Typst markup:
```
The show rule will wrap everything that comes after it in its function. The
-[`with` mehtod]($type/function.with) allows us to pass arguments, in this case,
-the column count, to a function without calling it.
+[`with` mehtod]($function.with) allows us to pass arguments, in this case, the
+column count, to a function without calling it.
Another use of the `columns` function is to create columns inside of a container
like a rectangle or to customize gutter size:
@@ -523,24 +521,23 @@ like a rectangle or to customize gutter size:
)
```
-### Balanced columns { #balanced-columns }
+### Balanced columns
If the columns on the last page of a document differ greatly in length, they may
create a lopsided and unappealing layout. That's why typographers will often
equalize the length of columns on the last page. This effect is called balancing
columns. Typst cannot yet balance columns automatically. However, you can
-balance columns manually by placing [`[#colbreak()]`]($func/colbreak) at an
+balance columns manually by placing [`[#colbreak()]`]($colbreak) at an
appropriate spot in your markup, creating the desired column break manually.
-## One-off modifications { #one-off-modifications }
+## One-off modifications
You do not need to override your page settings if you need to insert a single
page with a different setup. For example, you may want to insert a page that's
flipped to landscape to insert a big table or change the margin and columns for
-your title page. In this case, you can call [`{page}`]($func/page) as a function
-with your content as an argument and the overrides as the other arguments. This
-will insert enough new pages with your overridden settings to place your content
-on them. Typst will revert to the page settings from the set rule after the
-call.
+your title page. In this case, you can call [`{page}`]($page) as a function with
+your content as an argument and the overrides as the other arguments. This will
+insert enough new pages with your overridden settings to place your content on
+them. Typst will revert to the page settings from the set rule after the call.
```example
>>> #set page("a6")
diff --git a/docs/guides/welcome.md b/docs/guides/welcome.md
index f48fe1e5..f648c1c0 100644
--- a/docs/guides/welcome.md
+++ b/docs/guides/welcome.md
@@ -7,6 +7,6 @@ Welcome to the Guides section! Here, you'll find helpful material for specific
user groups or use cases. Currently, one guide is available: An introduction
to Typst for LaTeX users. Feel free to propose other topics for guides!
-## List of Guides { #list-of-guides }
+## List of Guides
- [Guide for LaTeX users]($guides/guide-for-latex-users)
- [Page setup guide]($guides/page-setup-guide)