Improve documentation on syntactical modes (#3419)

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md
index c03d6ab3..643dc954 100644
--- a/docs/reference/syntax.md
+++ b/docs/reference/syntax.md
@@ -11,6 +11,23 @@ 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