mirror of
https://github.com/typst/typst
synced 2025-05-14 04:56:26 +08:00
216 lines
12 KiB
Markdown
216 lines
12 KiB
Markdown
---
|
|
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.
|