From 09b364e9a35bf5746b932a4bcadf69fbc45521d2 Mon Sep 17 00:00:00 2001
From: Malo <57839069+MDLC01@users.noreply.github.com>
Date: Thu, 15 Feb 2024 14:49:29 +0100
Subject: Improve documentation on syntactical modes (#3419)

---
 docs/reference/syntax.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'docs')

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
-- 
cgit v1.2.3