Spaces:
Sleeping
Sleeping
File size: 12,785 Bytes
2d83f30 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 |
---
description: |
A compact reference for Typst's syntax. Learn more about the language within
markup, math, and code mode.
---
# Syntax
Typst is a markup language. This means that you can use simple syntax to
accomplish common layout tasks. The lightweight markup syntax is complemented by
set and show rules, which let you style your document easily and automatically.
All this is backed by a tightly integrated scripting language with built-in and
user-defined functions.
## Modes
Typst has three syntactical modes: Markup, math, and code. Markup mode is the
default in a Typst document, math mode lets you write mathematical formulas, and
code mode lets you use Typst's scripting features.
You can switch to a specific mode at any point by referring to the following
table:
| New mode | Syntax | Example |
|----------|---------------------------------|---------------------------------|
| Code | Prefix the code with `#` | `[Number: #(1 + 2)]` |
| Math | Surround equation with `[$..$]` | `[$-x$ is the opposite of $x$]` |
| Markup | Surround markup with `[[..]]` | `{let name = [*Typst!*]}` |
Once you have entered code mode with `#`, you don't need to use further hashes
unless you switched back to markup or math mode in between.
## Markup
Typst provides built-in markup for the most common document elements. Most of
the syntax elements are just shortcuts for a corresponding function. The table
below lists all markup that is available and links to the best place to learn
more about their syntax and usage.
| Name | Example | See |
| ------------------ | ---------------------------- | ------------------------ |
| Paragraph break | Blank line | [`parbreak`] |
| Strong emphasis | `[*strong*]` | [`strong`] |
| Emphasis | `[_emphasis_]` | [`emph`] |
| Raw text | ``[`print(1)`]`` | [`raw`] |
| Link | `[https://typst.app/]` | [`link`] |
| Label | `[<intro>]` | [`label`] |
| Reference | `[@intro]` | [`ref`] |
| Heading | `[= Heading]` | [`heading`] |
| Bullet list | `[- item]` | [`list`] |
| Numbered list | `[+ item]` | [`enum`] |
| Term list | `[/ Term: description]` | [`terms`] |
| Math | `[$x^2$]` | [Math]($category/math) |
| Line break | `[\]` | [`linebreak`] |
| Smart quote | `['single' or "double"]` | [`smartquote`] |
| Symbol shorthand | `[~]`, `[---]` | [Symbols]($category/symbols/sym) |
| Code expression | `[#rect(width: 1cm)]` | [Scripting]($scripting/#expressions) |
| Character escape | `[Tweet at us \#ad]` | [Below](#escapes) |
| Comment | `[/* block */]`, `[// line]` | [Below](#comments) |
## Math mode { #math }
Math mode is a special markup mode that is used to typeset mathematical
formulas. It is entered by wrapping an equation in `[$]` characters. This works
both in markup and code. The equation will be typeset into its own block if it
starts and ends with at least one space (e.g. `[$ x^2 $]`). Inline math can be
produced by omitting the whitespace (e.g. `[$x^2$]`). An overview over the
syntax specific to math mode follows:
| Name | Example | See |
| ---------------------- | ------------------------ | ------------------------ |
| Inline math | `[$x^2$]` | [Math]($category/math) |
| Block-level math | `[$ x^2 $]` | [Math]($category/math) |
| Bottom attachment | `[$x_1$]` | [`attach`]($category/math/attach) |
| Top attachment | `[$x^2$]` | [`attach`]($category/math/attach) |
| Fraction | `[$1 + (a+b)/5$]` | [`frac`]($math.frac) |
| Line break | `[$x \ y$]` | [`linebreak`] |
| Alignment point | `[$x &= 2 \ &= 3$]` | [Math]($category/math) |
| Variable access | `[$#x$, $pi$]` | [Math]($category/math) |
| Field access | `[$arrow.r.long$]` | [Scripting]($scripting/#fields) |
| Implied multiplication | `[$x y$]` | [Math]($category/math) |
| Symbol shorthand | `[$->$]`, `[$!=$]` | [Symbols]($category/symbols/sym) |
| Text/string in math | `[$a "is natural"$]` | [Math]($category/math) |
| Math function call | `[$floor(x)$]` | [Math]($category/math) |
| Code expression | `[$#rect(width: 1cm)$]` | [Scripting]($scripting/#expressions) |
| Character escape | `[$x\^2$]` | [Below](#escapes) |
| Comment | `[$/* comment */$]` | [Below](#comments) |
## Code mode { #code }
Within code blocks and expressions, new expressions can start without a leading
`#` character. Many syntactic elements are specific to expressions. Below is
a table listing all syntax that is available in code mode:
| Name | Example | See |
| ------------------------ | ----------------------------- | ---------------------------------- |
| None | `{none}` | [`none`] |
| Auto | `{auto}` | [`auto`] |
| Boolean | `{false}`, `{true}` | [`bool`] |
| Integer | `{10}`, `{0xff}` | [`int`] |
| Floating-point number | `{3.14}`, `{1e5}` | [`float`] |
| Length | `{2pt}`, `{3mm}`, `{1em}`, .. | [`length`] |
| Angle | `{90deg}`, `{1rad}` | [`angle`] |
| Fraction | `{2fr}` | [`fraction`] |
| Ratio | `{50%}` | [`ratio`] |
| String | `{"hello"}` | [`str`] |
| Label | `{<intro>}` | [`label`] |
| Math | `[$x^2$]` | [Math]($category/math) |
| Raw text | ``[`print(1)`]`` | [`raw`] |
| Variable access | `{x}` | [Scripting]($scripting/#blocks) |
| Code block | `{{ let x = 1; x + 2 }}` | [Scripting]($scripting/#blocks) |
| Content block | `{[*Hello*]}` | [Scripting]($scripting/#blocks) |
| Parenthesized expression | `{(1 + 2)}` | [Scripting]($scripting/#blocks) |
| Array | `{(1, 2, 3)}` | [Array]($array) |
| Dictionary | `{(a: "hi", b: 2)}` | [Dictionary]($dictionary) |
| Unary operator | `{-x}` | [Scripting]($scripting/#operators) |
| Binary operator | `{x + y}` | [Scripting]($scripting/#operators) |
| Assignment | `{x = 1}` | [Scripting]($scripting/#operators) |
| Field access | `{x.y}` | [Scripting]($scripting/#fields) |
| Method call | `{x.flatten()}` | [Scripting]($scripting/#methods) |
| Function call | `{min(x, y)}` | [Function]($function) |
| Argument spreading | `{min(..nums)}` | [Arguments]($arguments) |
| Unnamed function | `{(x, y) => x + y}` | [Function]($function) |
| Let binding | `{let x = 1}` | [Scripting]($scripting/#bindings) |
| Named function | `{let f(x) = 2 * x}` | [Function]($function) |
| Set rule | `{set text(14pt)}` | [Styling]($styling/#set-rules) |
| Set-if rule | `{set text(..) if .. }` | [Styling]($styling/#set-rules) |
| Show-set rule | `{show heading: set block(..)}` | [Styling]($styling/#show-rules) |
| Show rule with function | `{show raw: it => {..}}` | [Styling]($styling/#show-rules) |
| Show-everything rule | `{show: template}` | [Styling]($styling/#show-rules) |
| Context expression | `{context text.lang}` | [Context]($context) |
| Conditional | `{if x == 1 {..} else {..}}` | [Scripting]($scripting/#conditionals) |
| For loop | `{for x in (1, 2, 3) {..}}` | [Scripting]($scripting/#loops) |
| While loop | `{while x < 10 {..}}` | [Scripting]($scripting/#loops) |
| Loop control flow | `{break, continue}` | [Scripting]($scripting/#loops) |
| Return from function | `{return x}` | [Function]($function) |
| Include module | `{include "bar.typ"}` | [Scripting]($scripting/#modules) |
| Import module | `{import "bar.typ"}` | [Scripting]($scripting/#modules) |
| Import items from module | `{import "bar.typ": a, b, c}` | [Scripting]($scripting/#modules) |
| Comment | `{/* block */}`, `{// line}` | [Below](#comments) |
## Comments
Comments are ignored by Typst and will not be included in the output. This is
useful to exclude old versions or to add annotations. To comment out a single
line, start it with `//`:
```example
// our data barely supports
// this claim
We show with $p < 0.05$
that the difference is
significant.
```
Comments can also be wrapped between `/*` and `*/`. In this case, the comment
can span over multiple lines:
```example
Our study design is as follows:
/* Somebody write this up:
- 1000 participants.
- 2x2 data design. */
```
## Escape sequences { #escapes }
Escape sequences are used to insert special characters that are hard to type or
otherwise have special meaning in Typst. To escape a character, precede it with
a backslash. To insert any Unicode codepoint, you can write a hexadecimal escape
sequence: `[\u{1f600}]`. The same kind of escape sequences also work in
[strings]($str).
```example
I got an ice cream for
\$1.50! \u{1f600}
```
## Paths
Typst has various features that require a file path to reference external
resources such as images, Typst files, or data files. Paths are represented as
[strings]($str). There are two kinds of paths: Relative and absolute.
- A **relative path** searches from the location of the Typst file where the
feature is invoked. It is the default:
```typ
#image("images/logo.png")
```
- An **absolute path** searches from the _root_ of the project. It starts with a
leading `/`:
```typ
#image("/assets/logo.png")
```
### Project root
By default, the project root is the parent directory of the main Typst file.
For security reasons, you cannot read any files outside of the root directory.
If you want to set a specific folder as the root of your project, you can use
the CLI's `--root` flag. Make sure that the main file is contained in the
folder's subtree!
```bash
typst compile --root .. file.typ
```
In the web app, the project itself is the root directory. You can always read
all files within it, no matter which one is previewed (via the eye toggle next
to each Typst file in the file panel).
### Paths and packages
A package can only load files from its own directory. Within it, absolute paths
point to the package root, rather than the project root. For this reason, it
cannot directly load files from the project directory. If a package needs
resources from the project (such as a logo image), you must pass the already
loaded image, e.g. as a named parameter `{logo: image("mylogo.svg")}`. Note that
you can then still customize the image's appearance with a set rule within the
package.
In the future, paths might become a
[distinct type from strings](https://github.com/typst/typst/issues/971), so that
they can retain knowledge of where they were constructed. This way, resources
could be loaded from a different root.
|