From 029ae4a5ea7ad1e52112ce26b6d38ce1750dae3f Mon Sep 17 00:00:00 2001 From: Laurenz Date: Wed, 5 Feb 2025 14:24:10 +0100 Subject: Export target docs (#5812) Co-authored-by: Martin Haug <3874949+reknih@users.noreply.github.com> --- docs/reference/language/syntax.md | 215 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/reference/language/syntax.md (limited to 'docs/reference/language/syntax.md') diff --git a/docs/reference/language/syntax.md b/docs/reference/language/syntax.md new file mode 100644 index 00000000..fdc4d154 --- /dev/null +++ b/docs/reference/language/syntax.md @@ -0,0 +1,215 @@ +--- +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 | `[]` | [`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 | `{}` | [`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. -- cgit v1.2.3