// our data barely supports\n// this claim\n\nWe show with $p < 0.05$\nthat the difference is\nsignificant.\n![\"Preview\"](\"/en-US-v0.14.1/assets/aa63c9c9fd83801f26f5ba5d0dc73151.png\")
Typst is a markup language. This means that you can use simple syntax to\naccomplish common layout tasks. The lightweight markup syntax is complemented by\nset and show rules, which let you style your document easily and automatically.\nAll this is backed by a tightly integrated scripting language with built-in and\nuser-defined functions.
\nTypst has three syntactical modes: Markup, math, and code. Markup mode is the\ndefault in a Typst document, math mode lets you write mathematical formulas, and\ncode mode lets you use Typst's scripting features.
\nYou can switch to a specific mode at any point by referring to the following\ntable:
\n| 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\nunless you switched back to markup or math mode in between.
Typst provides built-in markup for the most common document elements. Most of\nthe syntax elements are just shortcuts for a corresponding function. The table\nbelow lists all markup that is available and links to the best place to learn\nmore about their syntax and usage.
\n| 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 |
| Line break | \\ | linebreak |
| Smart quote | 'single' or "double" | smartquote |
| Symbol shorthand | ~, --- | Symbols |
| Code expression | #rect(width: 1cm) | Scripting |
| Character escape | Tweet at us \\#ad | Below |
| Comment | /* block */, // line | Below |
Math mode is a special markup mode that is used to typeset mathematical\nformulas. It is entered by wrapping an equation in $ characters. This works\nboth in markup and code. The equation will be typeset into its own block if it\nstarts and ends with at least one space (e.g. $ x^2 $). Inline math can be\nproduced by omitting the whitespace (e.g. $x^2$). An overview over the\nsyntax specific to math mode follows:
| Name | Example | See |
|---|---|---|
| Inline math | $x^2$ | Math |
| Block-level math | $ x^2 $ | Math |
| Bottom attachment | $x_1$ | attach |
| Top attachment | $x^2$ | attach |
| Fraction | $1 + (a+b)/5$ | frac |
| Line break | $x \\ y$ | linebreak |
| Alignment point | $x &= 2 \\ &= 3$ | Math |
| Variable access | $#x$, $pi$ | Math |
| Field access | $arrow.r.long$ | Scripting |
| Implied multiplication | $x y$ | Math |
| Symbol shorthand | $->$, $!=$ | Symbols |
| Text/string in math | $a "is natural"$ | Math |
| Math function call | $floor(x)$ | Math |
| Code expression | $#rect(width: 1cm)$ | Scripting |
| Character escape | $x\\^2$ | Below |
| Comment | $/* comment */$ | Below |
Within code blocks and expressions, new expressions can start without a leading\n# character. Many syntactic elements are specific to expressions. Below is\na 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 |
| Raw text | `print(1)` | raw |
| Variable access | x | Scripting |
| Code block | { let x = 1; x + 2 } | Scripting |
| Content block | [*Hello*] | Scripting |
| Parenthesized expression | (1 + 2) | Scripting |
| Array | (1, 2, 3) | Array |
| Dictionary | (a: "hi", b: 2) | Dictionary |
| Unary operator | -x | Scripting |
| Binary operator | x + y | Scripting |
| Assignment | x = 1 | Scripting |
| Field access | x.y | Scripting |
| Method call | x.flatten() | Scripting |
| Function call | min(x, y) | Function |
| Argument spreading | min(..nums) | Arguments |
| Unnamed function | (x, y) => x + y | Function |
| Let binding | let x = 1 | Scripting |
| Named function | let f(x) = 2 * x | Function |
| Set rule | set text(14pt) | Styling |
| Set-if rule | set text(..) if .. | Styling |
| Show-set rule | show heading: set block(..) | Styling |
| Show rule with function | show raw: it => {..} | Styling |
| Show-everything rule | show: template | Styling |
| Context expression | context text.lang | Context |
| Conditional | if x == 1 {..} else {..} | Scripting |
| For loop | for x in (1, 2, 3) {..} | Scripting |
| While loop | while x < 10 {..} | Scripting |
| Loop control flow | break, continue | Scripting |
| Return from function | return x | Function |
| Include module | include "bar.typ" | Scripting |
| Import module | import "bar.typ" | Scripting |
| Import items from module | import "bar.typ": a, b, c | Scripting |
| Comment | /* block */, // line | Below |
Comments are ignored by Typst and will not be included in the output. This is\nuseful to exclude old versions or to add annotations. To comment out a single\nline, start it with //:
// our data barely supports\n// this claim\n\nWe show with $p < 0.05$\nthat the difference is\nsignificant.\nComments can also be wrapped between /* and */. In this case, the comment\ncan span over multiple lines:
Our study design is as follows:\n/* Somebody write this up:\n - 1000 participants.\n - 2x2 data design. */\n![\"Preview\"](\"/en-US-v0.14.1/assets/d1b7773edfcc1952006a027c9e9b8c30.png\")
Escape sequences are used to insert special characters that are hard to type or\notherwise have special meaning in Typst. To escape a character, precede it with\na backslash. To insert any Unicode codepoint, you can write a hexadecimal escape\nsequence: \\u{1f600}. The same kind of escape sequences also work in\nstrings.
I got an ice cream for\n\\$1.50! \\u{1f600}\n![\"Preview\"](\"/en-US-v0.14.1/assets/d87ab5c15ab42543dde046ab1ad05951.png\")
Names of variables, functions, and so on (identifiers) can contain letters,\nnumbers, hyphens (-), and underscores (_). They must start with a letter or\nan underscore.
More specifically, the identifier syntax in Typst is based on the\nUnicode Standard Annex #31, with two\nextensions: Allowing _ as a starting character, and allowing both _ and -\nas continuing characters.
For multi-word identifiers, the recommended case convention is\nKebab case. In Kebab\ncase, words are written in lowercase and separated by hyphens (as in\ntop-edge). This is especially relevant when developing modules and packages\nfor others to use, as it keeps things predictable.
#let kebab-case = [Using hyphen]\n#let _schön = "😊"\n#let 始料不及 = "😱"\n#let π = calc.pi\n\n#kebab-case\n#if -π < 0 { _schön } else { 始料不及 }\n// -π means -1 * π,\n// so it's not a valid identifier\n![\"Preview\"](\"/en-US-v0.14.1/assets/77fa42f9351fc5ea2759a99ce3d73e26.png\")
Typst has various features that require a file path to reference external\nresources such as images, Typst files, or data files. Paths are represented as\nstrings. There are two kinds of paths: Relative and absolute.
\nA relative path searches from the location of the Typst file where the\nfeature is invoked. It is the default:
\n#image("images/logo.png")\nAn absolute path searches from the root of the project. It starts with a\nleading /:
#image("/assets/logo.png")\nBy default, the project root is the parent directory of the main Typst file.\nFor security reasons, you cannot read any files outside of the root directory.
\nIf you want to set a specific folder as the root of your project, you can use\nthe CLI's --root flag. Make sure that the main file is contained in the\nfolder's subtree!
\ntypst compile --root .. file.typ\n\n
In the web app, the project itself is the root directory. You can always read\nall files within it, no matter which one is previewed (via the eye toggle next\nto each Typst file in the file panel).
\nA package can only load files from its own directory. Within it, absolute paths\npoint to the package root, rather than the project root. For this reason, it\ncannot directly load files from the project directory. If a package needs\nresources from the project (such as a logo image), you must pass the already\nloaded image, e.g. as a named parameter logo: image("mylogo.svg"). Note that\nyou can then still customize the image's appearance with a set rule within the\npackage.
In the future, paths might become a\ndistinct type from strings, so that\nthey can retain knowledge of where they were constructed. This way, resources\ncould be loaded from a different root.
"}}