Improve documentation on syntactical modes (#3419)

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")

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

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