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: [PATCH] Improve documentation on syntactical modes (#3419)

---
 crates/typst/src/foundations/mod.rs |  3 ++-
 crates/typst/src/text/raw.rs        |  5 +++--
 docs/reference/syntax.md            | 17 +++++++++++++++++
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/crates/typst/src/foundations/mod.rs b/crates/typst/src/foundations/mod.rs
index 543fb7743..f9e15bece 100644
--- a/crates/typst/src/foundations/mod.rs
+++ b/crates/typst/src/foundations/mod.rs
@@ -257,7 +257,8 @@ pub fn eval(
     engine: &mut Engine,
     /// A string of Typst code to evaluate.
     source: Spanned<String>,
-    /// The syntactical mode in which the string is parsed.
+    /// The [syntactical mode]($reference/syntax/#modes) in which the string is
+    /// parsed.
     ///
     /// ```example
     /// #eval("= Heading", mode: "markup")
diff --git a/crates/typst/src/text/raw.rs b/crates/typst/src/text/raw.rs
index e6918a7d3..bcaefe265 100644
--- a/crates/typst/src/text/raw.rs
+++ b/crates/typst/src/text/raw.rs
@@ -141,8 +141,9 @@ pub struct RawElem {
     /// The language to syntax-highlight in.
     ///
     /// Apart from typical language tags known from Markdown, this supports the
-    /// `{"typ"}` and `{"typc"}` tags for Typst markup and Typst code,
-    /// respectively.
+    /// `{"typ"}` and `{"typc"}` tags for
+    /// [Typst markup]($reference/syntax/#markup) and
+    /// [Typst code]($reference/syntax/#code), respectively.
     ///
     /// ````example
     /// ```typ
diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md
index c03d6ab31..643dc9548 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