Make Rust happier about the inline documentation

library/src/basics/enum.rs

@@ -9,20 +9,8 @@ use crate::prelude::*;
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///
-/// ## Syntax
-/// This functions also has dedicated syntax:
-///
-/// - Starting a line with a plus sign creates an automatically numbered
-///   enumeration item.
-/// - Start a line with a number followed by a dot creates an explicitly
-///   numbered enumeration item.
-///
-/// Enumeration items can contain multiple paragraphs and other block-level
-/// content. All content that is indented more than an item's plus sign or dot
-/// becomes part of that item.
-///
 /// ## Example
-/// ```
+/// ```example
 /// Automatically numbered:
 /// + Preparations
 /// + Analysis
@@ -37,15 +25,26 @@ use crate::prelude::*;
 /// #enum[First][Second]
 /// ```
 ///
+/// ## Syntax
+/// This functions also has dedicated syntax:
+///
+/// - Starting a line with a plus sign creates an automatically numbered
+///   enumeration item.
+/// - Start a line with a number followed by a dot creates an explicitly
+///   numbered enumeration item.
+///
+/// Enumeration items can contain multiple paragraphs and other block-level
+/// content. All content that is indented more than an item's plus sign or dot
+/// becomes part of that item.
+///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The enumeration's children.
 ///
 ///   When using the enum syntax, adjacent items are automatically collected
 ///   into enumerations, even through constructs like for loops.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #for phase in (
 ///      "Launch",
 ///      "Orbit",
@@ -53,11 +52,10 @@ use crate::prelude::*;
 ///   ) [+ #phase]
 ///   ```
 ///
-/// - start: NonZeroUsize (named)
+/// - start: `NonZeroUsize` (named)
 ///   Which number to start the enumeration with.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #enum(
 ///     start: 3,
 ///     [Skipping],
@@ -65,14 +63,13 @@ use crate::prelude::*;
 ///   )
 ///   ```
 ///
-/// - tight: bool (named)
+/// - tight: `bool` (named)
 ///   If this is `{false}`, the items are spaced apart with
-///   [enum spacing](@enum/spacing). If it is `{true}`, they use normal
+///   [enum spacing]($func/enum.spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the enumeration more compact,
+///   [leading]($func/par.leading) instead. This makes the enumeration more
-///   which can look better if the items are short.
+///   compact, which can look better if the items are short.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   + If an enum has a lot of text, and
 ///     maybe other inline content, it
 ///     should not be tight anymore.
@@ -97,10 +94,9 @@ pub struct EnumNode {
 #[node]
 impl EnumNode {
     /// How to number the enumeration. Accepts a
-    /// [numbering pattern or function](@numbering).
+    /// [numbering pattern or function]($func/numbering).
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set enum(numbering: "(a)")
     ///
     /// + Different
@@ -121,7 +117,7 @@ impl EnumNode {
 
     /// The spacing between the items of a wide (non-tight) enumeration.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

library/src/basics/heading.rs

@@ -16,14 +16,15 @@ use crate::text::{SpaceNode, TextNode, TextSize};
 ///
 /// Typst can automatically number your headings for you. To enable numbering,
 /// specify how you want your headings to be numbered with a
-/// [numbering pattern or function](@numbering).
+/// [numbering pattern or function]($func/numbering).
 ///
 /// Independently from the numbering, Typst can also automatically generate an
-/// [outline](@outline) of all headings for you. To exclude one or more headings
+/// [outline]($func/outline) of all headings for you. To exclude one or more
-/// from this outline, you can set the `outlined` parameter to `{false}`.
+/// headings from this outline, you can set the `outlined` parameter to
+/// `{false}`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set heading(numbering: "1.a)")
 ///
 /// = Introduction
@@ -39,10 +40,10 @@ use crate::text::{SpaceNode, TextNode, TextSize};
 /// signs determines the heading's logical nesting depth.
 ///
 /// ## Parameters
-/// - title: Content (positional, required)
+/// - title: `Content` (positional, required)
 ///   The heading's title.
 ///
-/// - level: NonZeroUsize (named)
+/// - level: `NonZeroUsize` (named)
 ///   The logical nesting depth of the heading, starting from one.
 ///
 /// ## Category
@@ -61,10 +62,9 @@ pub struct HeadingNode {
 #[node]
 impl HeadingNode {
     /// How to number the heading. Accepts a
-    /// [numbering pattern or function](@numbering).
+    /// [numbering pattern or function]($func/numbering).
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set heading(numbering: "1.a.")
     ///
     /// = A section
@@ -76,8 +76,7 @@ impl HeadingNode {
 
     /// Whether the heading should appear in the outline.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #outline()
     ///
     /// #heading[Normal]

library/src/basics/list.rs

@@ -8,14 +8,8 @@ use crate::text::TextNode;
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.
 ///
-/// ## Syntax
-/// This functions also has dedicated syntax: Start a line with a hyphen,
-/// followed by a space to create a list item. A list item can contain multiple
-/// paragraphs and other block-level content. All content that is indented
-/// more than an item's hyphen becomes part of that item.
-///
 /// ## Example
-/// ```
+/// ```example
 /// - *Content*
 ///   - Basics
 ///   - Text
@@ -34,28 +28,32 @@ use crate::text::TextNode;
 ///   )
 /// ```
 ///
+/// ## Syntax
+/// This functions also has dedicated syntax: Start a line with a hyphen,
+/// followed by a space to create a list item. A list item can contain multiple
+/// paragraphs and other block-level content. All content that is indented
+/// more than an item's hyphen becomes part of that item.
+///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The list's children.
 ///
 ///   When using the list syntax, adjacent items are automatically collected
 ///   into lists, even through constructs like for loops.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #for letter in "ABC" [
 ///     - Letter #letter
 ///   ]
 ///   ```
 ///
-/// - tight: bool (named)
+/// - tight: `bool` (named)
-///   If this is `{false}`, the items are spaced apart with
+///   If this is `{false}`, the items are spaced apart with [list
-///   [list spacing](@list/spacing). If it is `{true}`, they use normal
+///   spacing]($func/list.spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the list more compact, which
+///   [leading]($func/par.leading) instead. This makes the list more compact,
-///   can look better if the items are short.
+///   which can look better if the items are short.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   - If a list has a lot of text, and
 ///     maybe other inline content, it
 ///     should not be tight anymore.
@@ -80,8 +78,7 @@ pub struct ListNode {
 impl ListNode {
     /// The marker which introduces each element.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set list(marker: [--])
     ///
     /// - A more classic list
@@ -100,7 +97,7 @@ impl ListNode {
 
     /// The spacing between the items of a wide (non-tight) list.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

library/src/basics/table.rs

@@ -7,11 +7,11 @@ use crate::prelude::*;
 /// Tables are used to arrange content in cells. Cells can contain arbitrary
 /// content, including multiple paragraphs and are specified in row-major order.
 /// Because tables are just grids with configurable cell properties, refer to
-/// the [grid documentation](@grid) for more information on how to size the
+/// the [grid documentation]($func/grid) for more information on how to size the
 /// table tracks.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #table(
 ///   columns: (1fr, auto, auto),
 ///   inset: 10pt,
@@ -31,28 +31,30 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - cells: Content (positional, variadic)
+/// - cells: `Content` (positional, variadic)
 ///   The contents of the table cells.
 ///
-/// - rows: TrackSizings (named)
+/// - rows: `TrackSizings` (named)
 ///   Defines the row sizes.
-///   See the [grid documentation](@grid) for more information on track sizing.
+///   See the [grid documentation]($func/grid) for more information on track
+///   sizing.
 ///
-/// - columns: TrackSizings (named)
+/// - columns: `TrackSizings` (named)
 ///   Defines the column sizes.
-///   See the [grid documentation](@grid) for more information on track sizing.
+///   See the [grid documentation]($func/grid) for more information on track
+///   sizing.
 ///
-/// - gutter: TrackSizings (named)
+/// - gutter: `TrackSizings` (named)
 ///   Defines the gaps between rows & columns.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
-/// - column-gutter: TrackSizings (named)
+/// - column-gutter: `TrackSizings` (named)
 ///   Defines the gaps between columns. Takes precedence over `gutter`.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
-/// - row-gutter: TrackSizings (named)
+/// - row-gutter: `TrackSizings` (named)
 ///   Defines the gaps between rows. Takes precedence over `gutter`.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
 /// ## Category
 /// basics
@@ -76,8 +78,7 @@ impl TableNode {
     /// passed the cell's column and row index, starting at zero. This can be
     /// used to implement striped tables.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #table(
     ///   fill: (col, _) => if calc.odd(col) { luma(240) } else { white },
     ///   align: (col, row) =>

library/src/basics/terms.rs

@@ -14,21 +14,20 @@ use crate::text::{SpaceNode, TextNode};
 /// followed by a term, a colon and a description creates a term list item.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// / Ligature: A merged glyph.
 /// / Kerning: A spacing adjustment
 ///   between two adjacent letters.
 /// ```
 ///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The term list's children.
 ///
 ///   When using the term list syntax, adjacent items are automatically
 ///   collected into term lists, even through constructs like for loops.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #for year, product in (
 ///     "1978": "TeX",
 ///     "1984": "LaTeX",
@@ -36,14 +35,13 @@ use crate::text::{SpaceNode, TextNode};
 ///   ) [/ #product: Born in #year.]
 ///   ```
 ///
-/// - tight: bool (named)
+/// - tight: `bool` (named)
 ///   If this is `{false}`, the items are spaced apart with [term list
-///   spacing](@terms/spacing). If it is `{true}`, they use normal
+///   spacing]($func/terms.spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the term list more compact,
+///   [leading]($func/par.leading) instead. This makes the term list more
-///   which can look better if the items are short.
+///   compact, which can look better if the items are short.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   / Fact: If a term list has a lot
 ///     of text, and maybe other inline
 ///     content, it should not be tight
@@ -74,8 +72,7 @@ impl TermsNode {
 
     /// The hanging indent of the description.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set terms(hanging-indent: 0pt)
     /// / Term: This term list does not
     ///   make use of hanging indents.
@@ -85,7 +82,7 @@ impl TermsNode {
 
     /// The spacing between the items of a wide (non-tight) term list.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

library/src/compute/calc.rs

@@ -41,14 +41,14 @@ pub fn calc() -> Module {
 /// Calculate the absolute value of a numeric value.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.abs(-5) \
 /// #calc.abs(5pt - 2cm) \
 /// #calc.abs(2fr)
 /// ```
 ///
 /// ## Parameters
-/// - value: ToAbs (positional, required)
+/// - value: `ToAbs` (positional, required)
 ///   The value whose absolute value to calculate.
 ///
 /// ## Category
@@ -76,14 +76,14 @@ castable! {
 /// Raise a value to some exponent.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.pow(2, 3)
 /// ```
 ///
 /// ## Parameters
-/// - base: Num (positional, required)
+/// - base: `Num` (positional, required)
 ///   The base of the power.
-/// - exponent: Num (positional, required)
+/// - exponent: `Num` (positional, required)
 ///   The exponent of the power. Must be non-negative.
 ///
 /// ## Category
@@ -107,13 +107,13 @@ pub fn pow(args: &mut Args) -> SourceResult<Value> {
 /// Calculate the square root of a number.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.sqrt(16) \
 /// #calc.sqrt(2.5)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number whose square root to calculate. Must be non-negative.
 ///
 /// ## Category
@@ -134,14 +134,14 @@ pub fn sqrt(args: &mut Args) -> SourceResult<Value> {
 /// radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(calc.sin(90deg) == calc.sin(-270deg))
 /// #calc.sin(1.5) \
 /// #calc.sin(90deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose sine to calculate.
 ///
 /// ## Category
@@ -163,14 +163,14 @@ pub fn sin(args: &mut Args) -> SourceResult<Value> {
 /// radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.cos(90deg)
 /// #calc.cos(1.5) \
 /// #calc.cos(90deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose cosine to calculate.
 ///
 /// ## Category
@@ -192,13 +192,13 @@ pub fn cos(args: &mut Args) -> SourceResult<Value> {
 /// radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.tan(1.5) \
 /// #calc.tan(90deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose tangent to calculate.
 ///
 /// ## Category
@@ -217,13 +217,13 @@ pub fn tan(args: &mut Args) -> SourceResult<Value> {
 /// Calculate the arcsine of a number.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.asin(0) \
 /// #calc.asin(1)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number whose arcsine to calculate. Must be between -1 and 1.
 ///
 /// ## Category
@@ -242,13 +242,13 @@ pub fn asin(args: &mut Args) -> SourceResult<Value> {
 /// Calculate the arccosine of a number.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.acos(0) \
 /// #calc.acos(1)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number whose arccosine to calculate. Must be between -1 and 1.
 ///
 /// ## Category
@@ -267,13 +267,13 @@ pub fn acos(args: &mut Args) -> SourceResult<Value> {
 /// Calculate the arctangent of a number.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.atan(0) \
 /// #calc.atan(1)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number whose arctangent to calculate.
 ///
 /// ## Category
@@ -290,13 +290,13 @@ pub fn atan(args: &mut Args) -> SourceResult<Value> {
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.sinh(0) \
 /// #calc.sinh(45deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose hyperbolic sine to calculate.
 ///
 /// ## Category
@@ -317,13 +317,13 @@ pub fn sinh(args: &mut Args) -> SourceResult<Value> {
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.cosh(0) \
 /// #calc.cosh(45deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose hyperbolic cosine to calculate.
 ///
 /// ## Category
@@ -344,13 +344,13 @@ pub fn cosh(args: &mut Args) -> SourceResult<Value> {
 /// When called with an integer or a float, they will be interpreted as radians.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.tanh(0) \
 /// #calc.tanh(45deg)
 /// ```
 ///
 /// ## Parameters
-/// - angle: AngleLike (positional, required)
+/// - angle: `AngleLike` (positional, required)
 ///   The angle whose hyperbolic tangent to calculate.
 ///
 /// ## Category
@@ -371,14 +371,14 @@ pub fn tanh(args: &mut Args) -> SourceResult<Value> {
 /// If the base is not specified, the logarithm is calculated in base 10.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.log(100) \
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number whose logarithm to calculate.
-/// - base: Num (named)
+/// - base: `Num` (named)
 ///   The base of the logarithm.
 ///
 /// ## Category
@@ -396,14 +396,14 @@ pub fn log(args: &mut Args) -> SourceResult<Value> {
 /// If the number is already an integer, it is returned unchanged.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(calc.floor(3.14) == 3)
 /// #assert(calc.floor(3) == 3)
 /// #calc.floor(500.1)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number to round down.
 ///
 /// ## Category
@@ -423,14 +423,14 @@ pub fn floor(args: &mut Args) -> SourceResult<Value> {
 /// If the number is already an integer, it is returned unchanged.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(calc.ceil(3.14) == 4)
 /// #assert(calc.ceil(3) == 3)
 /// #calc.ceil(500.1)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number to round up.
 ///
 /// ## Category
@@ -450,16 +450,16 @@ pub fn ceil(args: &mut Args) -> SourceResult<Value> {
 /// Optionally, a number of decimal places can be specified.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(calc.round(3.14) == 3)
 /// #assert(calc.round(3.5) == 4)
 /// #calc.round(3.1415, digits: 2)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number to round.
-/// - digits: i64 (named)
+/// - digits: `i64` (named)
 ///
 /// ## Category
 /// calculate
@@ -481,18 +481,18 @@ pub fn round(args: &mut Args) -> SourceResult<Value> {
 /// Clamp a number between a minimum and maximum value.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(calc.clamp(5, 0, 10) == 5)
 /// #assert(calc.clamp(5, 6, 10) == 6)
 /// #calc.clamp(5, 0, 4)
 /// ```
 ///
 /// ## Parameters
-/// - value: Num (positional, required)
+/// - value: `Num` (positional, required)
 ///   The number to clamp.
-/// - min: Num (positional, required)
+/// - min: `Num` (positional, required)
 ///   The inclusive minimum value.
-/// - max: Num (positional, required)
+/// - max: `Num` (positional, required)
 ///   The inclusive maximum value.
 ///
 /// ## Category
@@ -512,13 +512,13 @@ pub fn clamp(args: &mut Args) -> SourceResult<Value> {
 /// Determine the minimum of a sequence of values.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.min(1, -3, -5, 20, 3, 6) \
 /// #calc.min("typst", "in", "beta")
 /// ```
 ///
 /// ## Parameters
-/// - values: Value (positional, variadic)
+/// - values: `Value` (positional, variadic)
 ///   The sequence of values from which to extract the minimum.
 ///   Must not be empty.
 ///
@@ -535,13 +535,13 @@ pub fn min(args: &mut Args) -> SourceResult<Value> {
 /// Determine the maximum of a sequence of values.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.max(1, -3, -5, 20, 3, 6) \
 /// #calc.max("typst", "in", "beta")
 /// ```
 ///
 /// ## Parameters
-/// - values: Value (positional, variadic)
+/// - values: `Value` (positional, variadic)
 ///   The sequence of values from which to extract the maximum.
 ///   Must not be empty.
 ///
@@ -579,14 +579,14 @@ fn minmax(args: &mut Args, goal: Ordering) -> SourceResult<Value> {
 /// Determine whether an integer is even.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.even(4) \
 /// #calc.even(5) \
 /// #range(10).filter(calc.even)
 /// ```
 ///
 /// ## Parameters
-/// - value: i64 (positional, required)
+/// - value: `i64` (positional, required)
 ///   The number to check for evenness.
 ///
 /// - returns: boolean
@@ -602,7 +602,7 @@ pub fn even(args: &mut Args) -> SourceResult<Value> {
 /// Determine whether an integer is odd.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.odd(4) \
 /// #calc.odd(5) \
 /// #range(10).filter(calc.odd)
@@ -610,7 +610,7 @@ pub fn even(args: &mut Args) -> SourceResult<Value> {
 ///
 ///
 /// ## Parameters
-/// - value: i64 (positional, required)
+/// - value: `i64` (positional, required)
 ///   The number to check for oddness.
 ///
 /// - returns: boolean
@@ -626,16 +626,16 @@ pub fn odd(args: &mut Args) -> SourceResult<Value> {
 /// Calculate the modulus of two numbers.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #calc.mod(20, 6) \
 /// #calc.mod(1.75, 0.5)
 /// ```
 ///
 /// ## Parameters
-/// - dividend: Num (positional, required)
+/// - dividend: `Num` (positional, required)
 ///   The dividend of the modulus.
 ///
-/// - divisor: Num (positional, required)
+/// - divisor: `Num` (positional, required)
 ///   The divisor of the modulus.
 ///
 /// - returns: integer or float

library/src/compute/construct.rs

@@ -12,7 +12,7 @@ use crate::prelude::*;
 /// - Strings are parsed in base 10.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #int(false) \
 /// #int(true) \
 /// #int(2.7) \
@@ -20,7 +20,7 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - value: ToInt (positional, required)
+/// - value: `ToInt` (positional, required)
 ///   The value that should be converted to an integer.
 ///
 /// - returns: integer
@@ -52,7 +52,7 @@ castable! {
 ///   Exponential notation is supported.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #float(false) \
 /// #float(true) \
 /// #float(4) \
@@ -61,7 +61,7 @@ castable! {
 /// ```
 ///
 /// ## Parameters
-/// - value: ToFloat (positional, required)
+/// - value: `ToFloat` (positional, required)
 ///   The value that should be converted to a float.
 ///
 /// - returns: float
@@ -88,14 +88,14 @@ castable! {
 /// Create a grayscale color.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #for x in range(250, step: 50) {
 ///   square(fill: luma(x))
 /// }
 /// ```
 ///
 /// ## Parameters
-/// - gray: Component (positional, required)
+/// - gray: `Component` (positional, required)
 ///   The gray component.
 ///
 /// - returns: color
@@ -118,14 +118,14 @@ pub fn luma(args: &mut Args) -> SourceResult<Value> {
 /// moment. This will be fixed in the future.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #square(fill: rgb("#b1f2eb"))
 /// #square(fill: rgb(87, 127, 230))
 /// #square(fill: rgb(25%, 13%, 65%))
 /// ```
 ///
 /// ## Parameters
-/// - hex: EcoString (positional)
+/// - hex: `EcoString` (positional)
 ///   The color in hexadecimal notation.
 ///
 ///   Accepts three, four, six or eight hexadecimal digits and optionally
@@ -133,23 +133,22 @@ pub fn luma(args: &mut Args) -> SourceResult<Value> {
 ///
 ///   If this string is given, the individual components should not be given.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #text(16pt, rgb("#239dad"))[
 ///     *Typst*
 ///   ]
 ///   ```
 ///
-/// - red: Component (positional)
+/// - red: `Component` (positional)
 ///   The red component.
 ///
-/// - green: Component (positional)
+/// - green: `Component` (positional)
 ///   The green component.
 ///
-/// - blue: Component (positional)
+/// - blue: `Component` (positional)
 ///   The blue component.
 ///
-/// - alpha: Component (positional)
+/// - alpha: `Component` (positional)
 ///   The alpha component.
 ///
 /// - returns: color
@@ -196,23 +195,23 @@ castable! {
 /// the color.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #square(
 ///   fill: cmyk(27%, 0%, 3%, 5%)
 /// )
 /// ````
 ///
 /// ## Parameters
-/// - cyan: RatioComponent (positional, required)
+/// - cyan: `RatioComponent` (positional, required)
 ///   The cyan component.
 ///
-/// - magenta: RatioComponent (positional, required)
+/// - magenta: `RatioComponent` (positional, required)
 ///   The magenta component.
 ///
-/// - yellow: RatioComponent (positional, required)
+/// - yellow: `RatioComponent` (positional, required)
 ///   The yellow component.
 ///
-/// - key: RatioComponent (positional, required)
+/// - key: `RatioComponent` (positional, required)
 ///   The key component.
 ///
 /// - returns: color
@@ -244,7 +243,7 @@ castable! {
 /// Create a custom symbol with modifiers.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let envelope = symbol(
 ///   "🖂",
 ///   ("stamped", "🖃"),
@@ -261,7 +260,7 @@ castable! {
 /// ```
 ///
 /// ## Parameters
-/// - variants: Variant (positional, variadic)
+/// - variants: `Variant` (positional, variadic)
 ///   The variants of the symbol.
 ///
 ///   Can be a just a string consisting of a single character for the
@@ -309,7 +308,7 @@ castable! {
 /// - From labels the name is extracted.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #str(10) \
 /// #str(2.7) \
 /// #str(1e8) \
@@ -317,7 +316,7 @@ castable! {
 /// ```
 ///
 /// ## Parameters
-/// - value: ToStr (positional, required)
+/// - value: `ToStr` (positional, required)
 ///   The value that should be converted to a string.
 ///
 /// - returns: string
@@ -344,11 +343,11 @@ castable! {
 /// Create a label from a string.
 ///
 /// Inserting a label into content attaches it to the closest previous element
-/// that is not a space. Then, the element can be [referenced](@ref) and styled
+/// that is not a space. Then, the element can be [referenced]($func/ref) and
-/// through the label.
+/// styled through the label.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #show <a>: set text(blue)
 /// #show label("b"): set text(red)
 ///
@@ -361,7 +360,7 @@ castable! {
 /// its name in angle brackets. This works both in markup and code.
 ///
 /// ## Parameters
-/// - name: EcoString (positional, required)
+/// - name: `EcoString` (positional, required)
 ///   The name of the label.
 ///
 /// - returns: label
@@ -377,15 +376,14 @@ pub fn label(args: &mut Args) -> SourceResult<Value> {
 /// Create a regular expression from a string.
 ///
 /// The result can be used as a
-/// [show rule selector](/docs/reference/styling/#show-rules) and with
+/// [show rule selector]($styling/#show-rules) and with
-/// [string methods](/docs/reference/types/string/#methods) like `find`,
+/// [string methods]($type/string) like `find`, `split`, and `replace`.
-/// `split`, and `replace`.
 ///
 /// [See here](https://docs.rs/regex/latest/regex/#syntax) for a specification
 /// of the supported syntax.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// // Works with show rules.
 /// #show regex("\d+"): set text(red)
 ///
@@ -397,7 +395,7 @@ pub fn label(args: &mut Args) -> SourceResult<Value> {
 /// ```
 ///
 /// ## Parameters
-/// - regex: EcoString (positional, required)
+/// - regex: `EcoString` (positional, required)
 ///   The regular expression as a string.
 ///
 ///   Most regex escape sequences just work because they are not valid Typst
@@ -423,7 +421,7 @@ pub fn regex(args: &mut Args) -> SourceResult<Value> {
 /// range.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #range(5) \
 /// #range(2, 5) \
 /// #range(20, step: 4) \
@@ -432,13 +430,13 @@ pub fn regex(args: &mut Args) -> SourceResult<Value> {
 /// ```
 ///
 /// ## Parameters
-/// - start: i64 (positional)
+/// - start: `i64` (positional)
 ///   The start of the range (inclusive).
 ///
-/// - end: i64 (positional, required)
+/// - end: `i64` (positional, required)
 ///   The end of the range (exclusive).
 ///
-/// - step: i64 (named)
+/// - step: `i64` (named)
 ///   The distance between the generated numbers.
 ///
 /// - returns: array

library/src/compute/data.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// The file will be read and returned as a string.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let text = read("data.html")
 ///
 /// An example for a HTML file:\
@@ -18,7 +18,7 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - path: EcoString (positional, required)
+/// - path: `EcoString` (positional, required)
 ///   Path to a file.
 ///
 /// - returns: string
@@ -47,7 +47,7 @@ pub fn read(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
 /// stripped.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let results = csv("data.csv")
 ///
 /// #table(
@@ -58,10 +58,10 @@ pub fn read(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
 /// ```
 ///
 /// ## Parameters
-/// - path: EcoString (positional, required)
+/// - path: `EcoString` (positional, required)
 ///   Path to a CSV file.
 ///
-/// - delimiter: Delimiter (named)
+/// - delimiter: `Delimiter` (named)
 ///   The delimiter that separates columns in the CSV file.
 ///   Must be a single ASCII character.
 ///   Defaults to a comma.
@@ -149,7 +149,7 @@ fn format_csv_error(error: csv::Error) -> String {
 /// `unit`, and `weather`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let forecast(day) = block[
 ///   #square(
 ///     width: 2cm,
@@ -174,7 +174,7 @@ fn format_csv_error(error: csv::Error) -> String {
 /// ```
 ///
 /// ## Parameters
-/// - path: EcoString (positional, required)
+/// - path: `EcoString` (positional, required)
 ///   Path to a JSON file.
 ///
 /// - returns: dictionary or array
@@ -239,7 +239,7 @@ fn format_json_error(error: serde_json::Error) -> String {
 /// tags.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let findChild(elem, tag) = {
 ///   elem.children
 ///     .find(e => "tag" in e and e.tag == tag)
@@ -273,7 +273,7 @@ fn format_json_error(error: serde_json::Error) -> String {
 /// ```
 ///
 /// ## Parameters
-/// - path: EcoString (positional, required)
+/// - path: `EcoString` (positional, required)
 ///   Path to an XML file.
 ///
 /// - returns: array

library/src/compute/foundations.rs

@@ -10,7 +10,7 @@ use typst::syntax::Source;
 /// Returns the name of the value's type.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #type(12) \
 /// #type(14.7) \
 /// #type("hello") \
@@ -20,7 +20,7 @@ use typst::syntax::Source;
 /// ```
 ///
 /// ## Parameters
-/// - value: Value (positional, required)
+/// - value: `Value` (positional, required)
 ///   The value whose type's to determine.
 ///
 /// - returns: string
@@ -40,7 +40,7 @@ pub fn type_(args: &mut Args) -> SourceResult<Value> {
 /// integers, floats, strings, content, and functions.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #none vs #repr(none) \
 /// #"hello" vs #repr("hello") \
 /// #(1, 2) vs #repr((1, 2)) \
@@ -48,7 +48,7 @@ pub fn type_(args: &mut Args) -> SourceResult<Value> {
 /// ```
 ///
 /// ## Parameters
-/// - value: Value (positional, required)
+/// - value: `Value` (positional, required)
 ///   The value whose string representation to produce.
 ///
 /// - returns: string
@@ -67,12 +67,12 @@ pub fn repr(args: &mut Args) -> SourceResult<Value> {
 /// produce any output in the document.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #assert(1 < 2)
 /// ```
 ///
 /// ## Parameters
-/// - condition: bool (positional, required)
+/// - condition: `bool` (positional, required)
 ///   The condition that must be true for the assertion to pass.
 ///
 /// ## Category
@@ -97,13 +97,13 @@ pub fn assert(args: &mut Args) -> SourceResult<Value> {
 /// You shouldn't typically need this function, but it is there if you do.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #let markup = "= Heading\n _Emphasis_"
 /// #eval(markup)
 /// ```
 ///
 /// ## Parameters
-/// - source: String (positional, required)
+/// - source: `String` (positional, required)
 ///   A string of Typst markup to evaluate.
 ///
 ///   The markup and code in the string cannot interact with the file system.

library/src/compute/utility.rs

@@ -12,7 +12,7 @@ use crate::text::Case;
 /// sense. Use it as a placeholder to try layouts.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// = Blind Text
 /// #lorem(30)
 ///
@@ -21,7 +21,7 @@ use crate::text::Case;
 /// ```
 ///
 /// ## Parameters
-/// - words: usize (positional, required)
+/// - words: `usize` (positional, required)
 ///   The length of the blind text in words.
 ///
 /// - returns: string
@@ -41,12 +41,12 @@ pub fn lorem(args: &mut Args) -> SourceResult<Value> {
 /// content. It is defined either through a pattern string or an arbitrary
 /// function.
 ///
-/// A numbering pattern consists of [counting symbols](#parameters--numbering)
+/// A numbering pattern consists of counting symbols, for which the actual
-/// for which the actual number is substituted, their prefixes, and one suffix.
+/// number is substituted, their prefixes, and one suffix. The prefixes and the
-/// The prefixes and the suffix are repeated as-is.
+/// suffix are repeated as-is.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #numbering("1.1)", 1, 2, 3) \
 /// #numbering("1.a.i", 1, 2) \
 /// #numbering("I – 1", 12, 2) \
@@ -60,7 +60,7 @@ pub fn lorem(args: &mut Args) -> SourceResult<Value> {
 /// ```
 ///
 /// ## Parameters
-/// - numbering: Numbering (positional, required)
+/// - numbering: `Numbering` (positional, required)
 ///   Defines how the numbering works.
 ///
 ///   **Counting symbols** are `1`, `a`, `A`, `i`, `I` and `*`. They are
@@ -84,7 +84,7 @@ pub fn lorem(args: &mut Args) -> SourceResult<Value> {
 ///   numberings to the `numbering` function without caring whether they are
 ///   defined as a pattern or function.
 ///
-/// - numbers: NonZeroUsize (positional, variadic)
+/// - numbers: `NonZeroUsize` (positional, variadic)
 ///   The numbers to apply the numbering to. Must be positive.
 ///
 ///   If `numbering` is a pattern and more numbers than counting symbols are

library/src/layout/align.rs

@@ -4,7 +4,7 @@ use crate::prelude::*;
 /// Align content horizontally and vertically.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set align(center)
 ///
 /// Centered text, a sight to see \
@@ -14,10 +14,10 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to align.
 ///
-/// - alignment: Axes<Option<GenAlign>> (positional, settable)
+/// - alignment: `Axes<Option<GenAlign>>` (positional, settable)
 ///   The alignment along both axes.
 ///
 ///   Possible values for horizontal alignments are:
@@ -28,7 +28,7 @@ use crate::prelude::*;
 ///   - `right`
 ///
 ///   The `start` and `end` alignments are relative to the current [text
-///   direction](@text/dir).
+///   direction]($func/text.dir).
 ///
 ///   Possible values for vertical alignments are:
 ///   - `top`
@@ -39,8 +39,7 @@ use crate::prelude::*;
 ///   the `+` operator to get a `2d alignment`. For example, `top + right`
 ///   aligns the content to the top right corner.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #set page(height: 6cm)
 ///   #set text(lang: "ar")
 ///

library/src/layout/columns.rs

@@ -11,7 +11,7 @@ use crate::text::TextNode;
 /// necessary.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// = Towards Advanced Deep Learning
 ///
 /// #box(height: 68pt,
@@ -32,10 +32,10 @@ use crate::text::TextNode;
 /// ```
 ///
 /// ## Parameters
-/// - count: usize (positional, required)
+/// - count: `usize` (positional, required)
 ///   The number of columns.
 ///
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content that should be layouted into the columns.
 ///
 /// ## Category
@@ -151,12 +151,12 @@ impl Layout for ColumnsNode {
 /// # Column Break
 /// A forced column break.
 ///
-/// The function will behave like a [page break](@pagebreak) when used in a
+/// The function will behave like a [page break]($func/pagebreak) when used in a
 /// single column layout or the last column on a page. Otherwise, content after
 /// the column break will be placed in the next column.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set page(columns: 2)
 /// Preliminary findings from our
 /// ongoing research project have
@@ -174,7 +174,7 @@ impl Layout for ColumnsNode {
 /// ```
 ///
 /// ## Parameters
-/// - weak: bool (named)
+/// - weak: `bool` (named)
 ///   If `{true}`, the column break is skipped if the current column is already
 ///   empty.
 ///

library/src/layout/container.rs

@@ -11,11 +11,12 @@ use crate::prelude::*;
 /// explicitly.
 ///
 /// _Note:_ While the behavior above will be the default in the future, the
-/// transformation functions [`scale`](@scale), [`rotate`](@rotate), and
+/// transformation functions [`scale`]($func/scale), [`rotate`]($func/rotate),
-/// [`move`](@move) will currently yield inline nodes within paragraphs.
+/// and [`move`]($func/move) will currently yield inline nodes within
+/// paragraphs.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Refer to the docs
 /// #box(
 ///   height: 9pt,
@@ -25,13 +26,13 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The contents of the box.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The width of the box.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The height of the box.
 ///
 /// ## Category
@@ -109,7 +110,7 @@ impl Inline for BoxNode {}
 /// block-level. This is especially useful when writing show rules.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #[
 ///   #show heading: it => it.title
 ///   = No block
@@ -124,19 +125,19 @@ impl Inline for BoxNode {}
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The contents of the block.
 ///
-/// - spacing: Spacing (named, settable)
+/// - spacing: `Spacing` (named, settable)
 ///   The spacing around this block.
 ///
-/// - above: Spacing (named, settable)
+/// - above: `Spacing` (named, settable)
 ///   The spacing between this block and its predecessor. Takes precedence over
 ///   `spacing`.
 ///
 ///   The default value is `{1.2em}`.
 ///
-/// - below: Spacing (named, settable)
+/// - below: `Spacing` (named, settable)
 ///   The spacing between this block and its successor. Takes precedence
 ///   over `spacing`.
 ///

library/src/layout/grid.rs

@@ -35,7 +35,7 @@ use super::Spacing;
 /// `columns:` `{(auto, auto, auto)}`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set text(10pt, weight: "bold")
 /// #let cell = rect.with(
 ///   inset: 8pt,
@@ -60,30 +60,30 @@ use super::Spacing;
 /// ```
 ///
 /// ## Parameters
-/// - cells: Content (positional, variadic) The contents of the table cells.
+/// - cells: `Content` (positional, variadic) The contents of the table cells.
 ///
 ///   The cells are populated in row-major order.
 ///
-/// - rows: TrackSizings (named) Defines the row sizes.
+/// - rows: `TrackSizings` (named) Defines the row sizes.
 ///
 ///   If there are more cells than fit the defined rows, the last row is
 ///   repeated until there are no more cells.
 ///
-/// - columns: TrackSizings (named) Defines the column sizes.
+/// - columns: `TrackSizings` (named) Defines the column sizes.
 ///
 ///   Either specify a track size array or provide an integer to create a grid
 ///   with that many `{auto}`-sized columns. Note that opposed to rows and
 ///   gutters, providing a single track size will only ever create a single
 ///   column.
 ///
-/// - gutter: TrackSizings (named) Defines the gaps between rows & columns.
+/// - gutter: `TrackSizings` (named) Defines the gaps between rows & columns.
 ///
 ///   If there are more gutters than defined sizes, the last gutter is repeated.
 ///
-/// - column-gutter: TrackSizings (named) Defines the gaps between columns.
+/// - column-gutter: `TrackSizings` (named) Defines the gaps between columns.
 ///   Takes precedence over `gutter`.
 ///
-/// - row-gutter: TrackSizings (named) Defines the gaps between rows. Takes
+/// - row-gutter: `TrackSizings` (named) Defines the gaps between rows. Takes
 ///   precedence over `gutter`.
 ///
 /// ## Category

library/src/layout/hide.rs

@@ -9,13 +9,13 @@ use crate::prelude::*;
 /// not included in the output.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Hello Jane \
 /// #hide[Hello] Joe
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to hide.
 ///
 /// ## Category

library/src/layout/pad.rs

@@ -8,7 +8,7 @@ use crate::prelude::*;
 /// positional argument.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set align(center)
 ///
 /// #pad(x: 16pt, image("typing.jpg"))
@@ -17,28 +17,28 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to pad at the sides.
 ///
-/// - left: Rel<Length> (named)
+/// - left: `Rel<Length>` (named)
 ///   The padding at the left side.
 ///
-/// - right: Rel<Length> (named)
+/// - right: `Rel<Length>` (named)
 ///   The padding at the right side.
 ///
-/// - top: Rel<Length> (named)
+/// - top: `Rel<Length>` (named)
 ///   The padding at the top side.
 ///
-/// - bottom: Rel<Length> (named)
+/// - bottom: `Rel<Length>` (named)
 ///   The padding at the bottom side.
 ///
-/// - x: Rel<Length> (named)
+/// - x: `Rel<Length>` (named)
 ///   The horizontal padding. Both `left` and `right` take precedence over this.
 ///
-/// - y: Rel<Length> (named)
+/// - y: `Rel<Length>` (named)
 ///   The vertical padding. Both `top` and `bottom` take precedence over this.
 ///
-/// - rest: Rel<Length> (named)
+/// - rest: `Rel<Length>` (named)
 ///   The padding for all sides. All other parameters take precedence over this.
 ///
 /// ## Category

library/src/layout/page.rs

@@ -14,19 +14,19 @@ use crate::prelude::*;
 /// the pages will grow to fit their content on the respective axis.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The contents of the page(s).
 ///
 ///   Multiple pages will be created if the content does not fit on a single
 ///   page. A new page with the page properties prior to the function invocation
 ///   will be created after the body has been typeset.
 ///
-/// - paper: Paper (positional, settable)
+/// - paper: `Paper` (positional, settable)
 ///   A standard paper size to set width and height. When this is not specified,
 ///   Typst defaults to `{"a4"}` paper.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// >>> #set page(margin: auto)
 /// #set page("us-letter")
 ///
@@ -44,8 +44,7 @@ pub struct PageNode(pub Content);
 impl PageNode {
     /// The width of the page.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(
     ///   width: 3cm,
     ///   margin: (x: 0cm),
@@ -61,16 +60,15 @@ impl PageNode {
     /// The height of the page.
     ///
     /// If this is set to `{auto}`, page breaks can only be triggered manually
-    /// by inserting a [page break](@pagebreak). Most examples throughout this
+    /// by inserting a [page break]($func/pagebreak). Most examples throughout
-    /// documentation use `{auto}` for the height of the page to dynamically
+    /// this documentation use `{auto}` for the height of the page to
-    /// grow and shrink to fit their content.
+    /// dynamically grow and shrink to fit their content.
     #[property(resolve)]
     pub const HEIGHT: Smart<Length> = Smart::Custom(Paper::A4.height().into());
 
     /// Whether the page is flipped into landscape orientation.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(
     ///   "us-business-card",
     ///   flipped: true,
@@ -103,8 +101,7 @@ impl PageNode {
     ///   - `rest`: The margins on all sides except those for which the
     ///     dictionary explicitly sets a size.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(
     ///  width: 3cm,
     ///  height: 4cm,
@@ -122,8 +119,7 @@ impl PageNode {
 
     /// How many columns the page has.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(columns: 2, height: 4.8cm)
     /// Climate change is one of the most
     /// pressing issues of our time, with
@@ -144,8 +140,7 @@ impl PageNode {
     /// environmentally friendly and cost-effective to source pre-dyed pages and
     /// not set this property.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(fill: rgb("444352"))
     /// #set text(fill: rgb("fdfdfd"))
     /// *Dark mode enabled.*
@@ -162,8 +157,7 @@ impl PageNode {
     ///   the header.
     /// - `{none}`: The header will be empty.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set par(justify: true)
     /// #set page(
     ///   margin: (x: 24pt, y: 32pt),
@@ -185,8 +179,7 @@ impl PageNode {
     ///   the footer.
     /// - `{none}`: The footer will be empty.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set par(justify: true)
     /// #set page(
     ///   margin: (x: 24pt, y: 32pt),
@@ -205,8 +198,7 @@ impl PageNode {
     /// This content will be placed behind the page's body. It can be
     /// used to place a background image or a watermark.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(background: align(
     ///   center + horizon,
     ///   rotate(24deg,
@@ -226,8 +218,7 @@ impl PageNode {
     ///
     /// This content will overlay the page's body.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(foreground: align(
     ///   center + horizon,
     ///   text(24pt)[🥸],
@@ -355,7 +346,7 @@ impl Debug for PageNode {
 /// A manually forced page break. It must not be used inside any containers.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// The next page contains
 /// more details on compound theory.
 /// #pagebreak()
@@ -366,7 +357,7 @@ impl Debug for PageNode {
 /// ```
 ///
 /// ## Parameters
-/// - weak: bool (named)
+/// - weak: `bool` (named)
 ///   If `{true}`, the page break is skipped if the current page is already empty.
 ///
 /// ## Category

library/src/layout/par.rs

@@ -19,7 +19,7 @@ use crate::text::{
 /// paragraph of its own.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set par(indent: 1em, justify: true)
 /// #show par: set block(spacing: 0.65em)
 ///
@@ -36,7 +36,7 @@ use crate::text::{
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The contents of the paragraph.
 ///
 /// ## Category
@@ -54,8 +54,8 @@ impl ParNode {
     ///
     /// By typographic convention, paragraph breaks are indicated by either some
     /// space between paragraphs or indented first lines. Consider turning the
-    /// [paragraph spacing](@block/spacing) off when using this property (e.g.
+    /// [paragraph spacing]($func/block.spacing) off when using this property
-    /// using `[#show par: set block(spacing: 0pt)]`).
+    /// (e.g. using `[#show par: set block(spacing: 0pt)]`).
     #[property(resolve)]
     pub const INDENT: Length = Length::zero();
 
@@ -68,12 +68,12 @@ impl ParNode {
     /// Whether to justify text in its line.
     ///
     /// Hyphenation will be enabled for justified paragraphs if the [text
-    /// property hyphenate](@text/hyphenate) is set to `{auto}` and the current
+    /// property hyphenate]($func/text.hyphenate) is set to `{auto}` and the
-    /// language is known.
+    /// current language is known.
     ///
-    /// Note that the current [alignment](@align) still has an effect on the
+    /// Note that the current [alignment]($func/align) still has an effect on
-    /// placement of the last line except if it ends with a [justified line
+    /// the placement of the last line except if it ends with a [justified line
-    /// break](@linebreak/justify).
+    /// break]($func/linebreak.justify).
     pub const JUSTIFY: bool = false;
 
     /// How to determine line breaks.
@@ -83,8 +83,7 @@ impl ParNode {
     /// breaks for ragged paragraphs may also be worthwhile to improve the
     /// appearance of the text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set page(width: 190pt)
     /// #set par(linebreaks: "simple")
     /// Some texts are frustratingly
@@ -219,15 +218,11 @@ castable! {
 /// A paragraph break.
 ///
 /// This starts a new paragraph. Especially useful when used within code like
-/// [for loops](/docs/reference/scripting/#loops). Multiple consecutive
+/// [for loops]($scripting/#loops). Multiple consecutive
 /// paragraph breaks collapse into a single one.
 ///
-/// ## Syntax
-/// Instead of calling this function, you can insert a blank line into your
-/// markup to create a paragraph break.
-///
 /// ## Example
-/// ```
+/// ```example
 /// #for i in range(3) {
 ///   [Blind text #i: ]
 ///   lorem(5)
@@ -235,6 +230,10 @@ castable! {
 /// }
 /// ```
 ///
+/// ## Syntax
+/// Instead of calling this function, you can insert a blank line into your
+/// markup to create a paragraph break.
+///
 /// ## Category
 /// layout
 #[func]

library/src/layout/place.rs

@@ -9,7 +9,7 @@ use crate::prelude::*;
 ///
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set page(height: 60pt)
 /// Hello, world!
 ///
@@ -23,21 +23,20 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - alignment: Axes<Option<GenAlign>> (positional)
+/// - alignment: `Axes<Option<GenAlign>>` (positional)
 ///   Relative to which position in the parent container to place the content.
 ///
 ///   When an axis of the page is `{auto}` sized, all alignments relative to that
 ///   axis will be ignored, instead, the item will be placed in the origin of the
 ///   axis.
 ///
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to place.
 ///
-/// - dx: Rel<Length> (named)
+/// - dx: `Rel<Length>` (named)
 ///   The horizontal displacement of the placed content.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #set align(center)
 ///
 ///   #box(
@@ -52,7 +51,7 @@ use crate::prelude::*;
 ///   )
 ///   ```
 ///
-/// - dy: Rel<Length> (named)
+/// - dy: `Rel<Length>` (named)
 ///   The vertical displacement of the placed content.
 ///
 /// ## Category

library/src/layout/repeat.rs

@@ -9,7 +9,7 @@ use crate::prelude::*;
 /// sure to include negative space if you need the instances to overlap.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Sign on the dotted line: #repeat[.]
 ///
 /// #set text(10pt)
@@ -20,7 +20,7 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to repeat.
 ///
 /// ## Category

library/src/layout/spacing.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// according to their relative fractions.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #circle(fill: red)
 /// #h(1fr)
 /// #circle(fill: yellow)
@@ -18,17 +18,20 @@ use crate::prelude::*;
 /// #circle(fill: green)
 /// ```
 ///
+/// ## Mathematical Spacing
+/// In [mathematical formulas]($category/math), you can additionally use these
+/// constants to add spacing between elements: `thin`, `med`, `thick, `quad`.
+///
 /// ## Parameters
-/// - amount: Spacing (positional, required)
+/// - amount: `Spacing` (positional, required)
 ///   How much spacing to insert.
 ///
-/// - weak: bool (named)
+/// - weak: `bool` (named)
 ///   If true, the spacing collapses at the start or end of a paragraph.
 ///   Moreover, from multiple adjacent weak spacings all but the largest one
 ///   collapse.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #h(1cm, weak: true)
 ///   We identified a group of
 ///   _weak_ specimens that fail to
@@ -105,7 +108,7 @@ impl Behave for HNode {
 /// according to their relative fractions.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// In this report, we will explore
 /// the various ethical
 /// considerations that must be
@@ -121,17 +124,16 @@ impl Behave for HNode {
 /// ```
 ///
 /// ## Parameters
-/// - amount: Spacing (positional, required)
+/// - amount: `Spacing` (positional, required)
 ///   How much spacing to insert.
 ///
-/// - weak: bool (named)
+/// - weak: `bool` (named)
 ///   If true, the spacing collapses at the start or end of a flow. Moreover,
 ///   from multiple adjacent weak spacings all but the largest one collapse.
 ///   Weak spacings will always collapse adjacent paragraph spacing, even if the
 ///   paragraph spacing is larger.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   The following theorem is
 ///   foundational to the field:
 ///   #v(4pt, weak: true)

library/src/layout/stack.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// between each item.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #stack(
 ///   dir: ttb,
 ///   rect(width: 40pt),
@@ -20,10 +20,10 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - items: StackChild (positional, variadic)
+/// - items: `StackChild` (positional, variadic)
 ///   The items to stack along an axis.
 ///
-/// - dir: Dir (named)
+/// - dir: `Dir` (named)
 ///   The direction along which the items are stacked. Possible values are:
 ///
 ///   - `{ltr}`: Left to right.
@@ -31,7 +31,7 @@ use crate::prelude::*;
 ///   - `{ttb}`: Top to bottom.
 ///   - `{btt}`: Bottom to top.
 ///
-/// - spacing: Spacing (named)
+/// - spacing: `Spacing` (named)
 ///   Spacing to insert between items where no explicit spacing was provided.
 ///
 /// ## Category

library/src/layout/transform.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// was not moved.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #rect(inset: 0pt, move(
 ///   dx: 6pt, dy: 6pt,
 ///   rect(
@@ -23,18 +23,17 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to move.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   Hello, world!#move(dy: -2pt)[!]#move(dy: 2pt)[!]
 ///   ```
 ///
-/// - dx: Rel<Length> (named)
+/// - dx: `Rel<Length>` (named)
 ///   The horizontal displacement of the content.
 ///
-/// - dy: Rel<Length> (named)
+/// - dy: `Rel<Length>` (named)
 ///   The vertical displacement of the content.
 ///
 /// ## Category
@@ -95,7 +94,7 @@ impl Inline for MoveNode {}
 /// was not rotated.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #{
 ///   range(16)
 ///     .map(i => rotate(24deg * i)[X])
@@ -104,14 +103,13 @@ impl Inline for MoveNode {}
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to rotate.
 ///
-/// - angle: Angle (named)
+/// - angle: `Angle` (named)
 ///   The amount of rotation.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #rotate(angle: -1.571rad)[To space!]
 ///   ```
 ///
@@ -136,8 +134,7 @@ impl RotateNode {
     /// stay aligned with the baseline, you would set the origin to `bottom +
     /// left`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(spacing: 8pt)
     /// #let square = square.with(width: 8pt)
     ///
@@ -195,21 +192,21 @@ impl Inline for RotateNode {}
 ///
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set align(center)
 /// #scale(x: -100%)[👍]👩‍🦱👍
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to scale.
 ///
-/// - x: Ratio (named)
+/// - x: `Ratio` (named)
 ///   The horizontal scaling factor.
 ///
 ///   The body will be mirrored horizontally if the parameter is negative.
 ///
-/// - y: Ratio (named)
+/// - y: `Ratio` (named)
 ///   The vertical scaling factor.
 ///
 ///   The body will be mirrored vertically if the parameter is negative.
@@ -232,8 +229,7 @@ impl ScaleNode {
     ///
     /// By default, the origin is the center of the scaled element.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// A#scale(75%)[A]A \
     /// B#scale(75%, origin: bottom + left)[B]B
     /// ```

library/src/math/accent.rs

@@ -9,23 +9,22 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5);
 /// Attach an accent to a base.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $grave(a) = accent(a, `)$ \
 /// $arrow(a) = accent(a, arrow)$ \
 /// $tilde(a) = accent(a, \u{0303})$
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to which the accent is applied.
 ///   May consist of multiple letters.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   $arrow(A B C)$
 ///   ```
 ///
-/// - accent: char (positional, required)
+/// - accent: `char` (positional, required)
 ///   The accent to apply to the base.
 ///
 ///   Supported accents include:

library/src/math/align.rs

@@ -4,7 +4,7 @@ use super::*;
 /// A math alignment point: `&`, `&&`.
 ///
 /// ## Parameters
-/// - index: usize (positional, required)
+/// - index: `usize` (positional, required)
 ///   The alignment point's index.
 ///
 /// ## Category

library/src/math/attach.rs

@@ -8,18 +8,18 @@ use super::*;
 /// indicate a bottom attachment and the hat (`^`) to indicate a top attachment.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sum_(i=0)^n a_i = 2^(1+i) $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to which things are attached.
 ///
-/// - top: Content (named)
+/// - top: `Content` (named)
 ///   The top attachment.
 ///
-/// - bottom: Content (named)
+/// - bottom: `Content` (named)
 ///   The bottom attachment.
 ///
 /// ## Category
@@ -84,12 +84,12 @@ impl LayoutMath for AttachNode {
 /// Force a base to display attachments as scripts.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ scripts(sum)_1^2 != sum_1^2 $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to attach the scripts to.
 ///
 /// ## Category
@@ -116,12 +116,12 @@ impl LayoutMath for ScriptsNode {
 /// Force a base to display attachments as limits.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ limits(A)_1^2 != A_1^2 $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to attach the limits to.
 ///
 /// ## Category

library/src/math/delimited.rs

@@ -10,16 +10,16 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1);
 /// unmatched delimiters and to control the delimiter scaling more precisely.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ lr(]a, b/2]) $
 /// $ lr(]sum_(x=1)^n] x, size: #50%) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, variadic)
+/// - body: `Content` (positional, variadic)
 ///   The delimited content, including the delimiters.
 ///
-/// - size: Rel<Length> (named)
+/// - size: `Rel<Length>` (named)
 ///   The size of the brackets, relative to the height of the wrapped content.
 ///
 ///   Defaults to `{100%}`.
@@ -120,12 +120,12 @@ fn scale(
 /// Floor an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ floor(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to floor.
 ///
 /// ## Category
@@ -139,12 +139,12 @@ pub fn floor(args: &mut Args) -> SourceResult<Value> {
 /// Ceil an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ ceil(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to ceil.
 ///
 /// ## Category
@@ -158,12 +158,12 @@ pub fn ceil(args: &mut Args) -> SourceResult<Value> {
 /// Take the absolute value of an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ abs(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to take the absolute value of.
 ///
 /// ## Category
@@ -177,12 +177,12 @@ pub fn abs(args: &mut Args) -> SourceResult<Value> {
 /// Take the norm of an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ norm(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to take the norm of.
 ///
 /// ## Category

library/src/math/frac.rs

@@ -5,23 +5,23 @@ const FRAC_AROUND: Em = Em::new(0.1);
 /// # Fraction
 /// A mathematical fraction.
 ///
+/// ## Example
+/// ```example
+/// $ 1/2 < (x+1)/2 $
+/// $ ((x+1)) / 2 = frac(a, b) $
+/// ```
+///
 /// ## Syntax
 /// This function also has dedicated syntax: Use a slash to turn neighbouring
 /// expressions into a fraction. Multiple atoms can be grouped into a single
 /// expression using round grouping parenthesis. Such parentheses are removed
 /// from the output, but you can nest multiple to force them.
 ///
-/// ## Example
-/// ```
-/// $ 1/2 < (x+1)/2 $
-/// $ ((x+1)) / 2 = frac(a, b) $
-/// ```
-///
 /// ## Parameters
-/// - num: Content (positional, required)
+/// - num: `Content` (positional, required)
 ///   The fraction's numerator.
 ///
-/// - denom: Content (positional, required)
+/// - denom: `Content` (positional, required)
 ///   The fraction's denominator.
 ///
 /// ## Category
@@ -55,15 +55,15 @@ impl LayoutMath for FracNode {
 /// A binomial expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ binom(n, k) $
 /// ```
 ///
 /// ## Parameters
-/// - upper: Content (positional, required)
+/// - upper: `Content` (positional, required)
 ///   The binomial's upper index.
 ///
-/// - lower: Content (positional, required)
+/// - lower: `Content` (positional, required)
 ///   The binomial's lower index.
 ///
 /// ## Category

library/src/math/matrix.rs

@@ -10,13 +10,13 @@ const VERTICAL_PADDING: Ratio = Ratio::new(0.1);
 /// Content in the vector's elements can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ vec(a, b, c) dot vec(1, 2, 3)
 ///     = a + 2b + 3c $
 /// ```
 ///
 /// ## Parameters
-/// - elements: Content (positional, variadic)
+/// - elements: `Content` (positional, variadic)
 ///   The elements of the vector.
 ///
 /// ## Category
@@ -30,8 +30,7 @@ pub struct VecNode(Vec<Content>);
 impl VecNode {
     /// The delimiter to use.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set math.vec(delim: "[")
     /// $ vec(1, 2) $
     /// ```
@@ -62,7 +61,7 @@ impl LayoutMath for VecNode {
 /// Content in cells that are in the same row can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ mat(
 ///   1, 2, ..., 10;
 ///   2, 2, ..., 10;
@@ -72,11 +71,10 @@ impl LayoutMath for VecNode {
 /// ```
 ///
 /// ## Parameters
-/// - rows: Array (positional, variadic)
+/// - rows: `Array` (positional, variadic)
 ///   An array of arrays with the rows of the matrix.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #let data = ((1, 2, 3), (4, 5, 6))
 ///   #let matrix = math.mat(..data)
 ///   $ v := matrix $
@@ -93,8 +91,7 @@ pub struct MatNode(Vec<Vec<Content>>);
 impl MatNode {
     /// The delimiter to use.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set math.mat(delim: "[")
     /// $ mat(1, 2; 3, 4) $
     /// ```
@@ -140,7 +137,7 @@ impl LayoutMath for MatNode {
 /// Content across different branches can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ f(x, y) := cases(
 ///   1 "if" (x dot y)/2 <= 0,
 ///   2 "if" x "is even",
@@ -150,7 +147,7 @@ impl LayoutMath for MatNode {
 /// ```
 ///
 /// ## Parameters
-/// - branches: Content (positional, variadic)
+/// - branches: `Content` (positional, variadic)
 ///   The branches of the case distinction.
 ///
 /// ## Category

library/src/math/mod.rs

@@ -112,7 +112,7 @@ pub fn module() -> Module {
 /// Can be displayed inline with text or as a separate block.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set text("Latin Modern Roman")
 ///
 /// Let $a$, $b$, and $c$ be the side
@@ -129,13 +129,13 @@ pub fn module() -> Module {
 /// dollar signs to create a formula. Starting and ending the formula with at
 /// least one space lifts it into a separate block that is centered
 /// horizontally. For more details about math syntax, see the
-/// [main math page](/docs/reference/math).
+/// [main math page]($category/math).
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The contents of the formula.
 ///
-/// - block: bool (named)
+/// - block: `bool` (named)
 ///   Whether the formula is displayed as a separate block.
 ///
 /// ## Category

library/src/math/op.rs

@@ -5,10 +5,18 @@ use super::*;
 /// # Text Operator
 /// A text operator in a math formula.
 ///
+/// ## Predefined Operators
+/// Typst predefines the operators `arccos`,  `arcsin`,  `arctan`,  `arg`,
+/// `cos`,  `cosh`,  `cot`,  `coth`,  `csc`,  `deg`,  `det`,  `dim`,  `exp`,
+/// `gcd`,  `hom`,  `mod`,  `inf`,  `ker`,  `lg`,  `lim`,  `ln`,  `log`,  `max`,
+/// `min`,  `Pr`,  `sec`,  `sin`,  `sinh`,  `sup`,  `tan`,  `tanh`,  `liminf`,
+/// and `limsup`.
+///
 /// ## Parameters
-/// - text: EcoString (positional, required)
+/// - text: `EcoString` (positional, required)
 ///   The operator's text.
-/// - limits: bool (named)
+///
+/// - limits: `bool` (named)
 ///   Whether the operator should force attachments to display as limits.
 ///
 ///   Defaults to `{false}`.

library/src/math/root.rs

@@ -4,12 +4,12 @@ use super::*;
 /// A square root.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sqrt(x^2) = x = sqrt(x)^2 $
 /// ```
 ///
 /// ## Parameters
-/// - radicand: Content (positional, required)
+/// - radicand: `Content` (positional, required)
 ///   The expression to take the square root of.
 ///
 /// ## Category
@@ -36,15 +36,15 @@ impl LayoutMath for SqrtNode {
 /// A general root.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ root(3, x) $
 /// ```
 ///
 /// ## Parameters
-/// - index: Content (positional, required)
+/// - index: `Content` (positional, required)
 ///   Which root of the radicand to take.
 ///
-/// - radicand: Content (positional, required)
+/// - radicand: `Content` (positional, required)
 ///   The expression to take the root of.
 ///
 /// ## Category

library/src/math/style.rs

@@ -4,12 +4,12 @@ use super::*;
 /// Bold font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ bold(A) := B^+ $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -39,12 +39,12 @@ impl LayoutMath for BoldNode {
 /// Upright (non-italic) font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ upright(A) != A $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -76,7 +76,7 @@ impl LayoutMath for UprightNode {
 /// For roman letters and greek lowercase letters, this is already the default.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -108,7 +108,7 @@ impl LayoutMath for ItalicNode {
 /// This is already the default.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -138,12 +138,12 @@ impl LayoutMath for SerifNode {
 /// Sans-serif font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sans(A B C) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -173,12 +173,12 @@ impl LayoutMath for SansNode {
 /// Calligraphic font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Let $cal(P)$ be the set of ...
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -208,12 +208,12 @@ impl LayoutMath for CalNode {
 /// Fraktur font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ frak(P) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -243,12 +243,12 @@ impl LayoutMath for FrakNode {
 /// Monospace font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ mono(x + y = z) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -278,17 +278,18 @@ impl LayoutMath for MonoNode {
 /// Blackboard bold (double-struck) font style in math.
 ///
 /// For uppercase latin letters, blackboard bold is additionally available
-/// through [symbols](/docs/reference/math/symbols) of the form `NN` and `RR`.
+/// through [symbols]($category/symbols/sym) of the form `NN` and `RR`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ bb(b) $
 /// $ bb(N) = NN $
 /// $ f: NN -> RR $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required) The piece of formula to style.
+/// - body: `Content` (positional, required)
+///   The piece of formula to style.
 ///
 /// ## Category
 /// math

library/src/math/underover.rs

@@ -8,12 +8,12 @@ const BRACKET_GAP: Em = Em::new(0.25);
 /// A horizontal line under content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underline(1 + 2 + ... + 5) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the line.
 ///
 /// ## Category
@@ -40,12 +40,12 @@ impl LayoutMath for UnderlineNode {
 /// A horizontal line over content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overline(1 + 2 + ... + 5) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the line.
 ///
 /// ## Category
@@ -72,15 +72,15 @@ impl LayoutMath for OverlineNode {
 /// A horizontal brace under content, with an optional annotation below.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the brace.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content below the brace.
 ///
 /// ## Category
@@ -114,15 +114,15 @@ impl LayoutMath for UnderbraceNode {
 /// A horizontal brace over content, with an optional annotation above.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the brace.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content above the brace.
 ///
 /// ## Category
@@ -156,15 +156,15 @@ impl LayoutMath for OverbraceNode {
 /// A horizontal bracket under content, with an optional annotation below.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underbracket(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the bracket.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content below the bracket.
 ///
 /// ## Category
@@ -198,15 +198,15 @@ impl LayoutMath for UnderbracketNode {
 /// A horizontal bracket over content, with an optional annotation above.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overbracket(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the bracket.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content above the bracket.
 ///
 /// ## Category

library/src/meta/link.rs

@@ -10,7 +10,7 @@ use crate::text::TextNode;
 /// a style of your choice with a show rule.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #show link: underline
 ///
 /// https://example.com \
@@ -25,7 +25,7 @@ use crate::text::TextNode;
 /// `https://` is automatically turned into a link.
 ///
 /// ## Parameters
-/// - dest: Destination (positional, required)
+/// - dest: `Destination` (positional, required)
 ///   The destination the link points to.
 ///
 ///   - To link to web pages, `dest` should be a valid URL string. If the URL is
@@ -38,15 +38,14 @@ use crate::text::TextNode;
 ///     coordinates of type `length`. Pages are counted from one, and the
 ///     coordinates are relative to the page's top left corner.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #link("mailto:hello@typst.app") \
 ///   #link((page: 1, x: 0pt, y: 0pt))[
 ///     Go to top
 ///   ]
 ///   ```
 ///
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///
 ///   The content that should become a link. If `dest` is an URL string, the
 ///   parameter can be omitted. In this case, the URL will be shown as the link.

library/src/meta/outline.rs

@@ -7,11 +7,11 @@ use crate::text::{LinebreakNode, SpaceNode, TextNode};
 /// A section outline / table of contents.
 ///
 /// This function generates a list of all headings in the document, up to a
-/// given depth. The [heading](@heading) numbering will be reproduced within the
+/// given depth. The [heading]($func/heading) numbering will be reproduced
-/// outline.
+/// within the outline.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #outline()
 ///
 /// = Introduction
@@ -33,7 +33,7 @@ impl OutlineNode {
     /// The title of the outline.
     ///
     /// - When set to `{auto}`, an appropriate title for the [text
-    ///   language](@text/lang) will be used. This is the default.
+    ///   language]($func/text.lang) will be used. This is the default.
     /// - When set to `{none}`, the outline will not have a title.
     /// - A custom title can be set by passing content.
     #[property(referenced)]
@@ -45,10 +45,9 @@ impl OutlineNode {
 
     /// Whether to indent the subheadings to align the start of their numbering
     /// with the title of their parents. This will only have an effect if a
-    /// [heading numbering](@heading/numbering) is set.
+    /// [heading numbering]($func/heading.numbering) is set.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set heading(numbering: "1.a.")
     ///
     /// #outline(indent: true)
@@ -67,8 +66,7 @@ impl OutlineNode {
     /// number. Can be set to `none` to disable filling. The default is a
     /// single dot.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #outline(
     ///   fill: pad(x: -1.5pt)[―]
     /// )

library/src/meta/reference.rs

@@ -17,7 +17,7 @@ use crate::text::TextNode;
 /// Introduction <intro>]` can be referenced by typing `[@intro]`).
 ///
 /// ## Parameters
-/// - target: Label (positional, required)
+/// - target: `Label` (positional, required)
 ///   The label that should be referenced.
 ///
 /// ## Category

library/src/text/deco.rs

@@ -8,12 +8,12 @@ use crate::prelude::*;
 /// Underline text.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// This is #underline[important].
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to underline.
 ///
 /// ## Category
@@ -28,8 +28,7 @@ impl UnderlineNode {
     /// How to stroke the line. The text color and thickness are read from the
     /// font tables if `{auto}`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// Take #underline(
     ///   stroke: 1.5pt + red,
     ///   offset: 2pt,
@@ -42,8 +41,7 @@ impl UnderlineNode {
     /// Position of the line relative to the baseline, read from the font tables
     /// if `{auto}`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #underline(offset: 5pt)[
     ///   The Tale Of A Faraway Line I
     /// ]
@@ -53,8 +51,7 @@ impl UnderlineNode {
 
     /// Amount that the line will be longer or shorter than its associated text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #align(center,
     ///   underline(extent: 2pt)[Chapter 1]
     /// )
@@ -65,8 +62,7 @@ impl UnderlineNode {
     /// Whether the line skips sections in which it would collide with the
     /// glyphs.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// This #underline(evade: true)[is great].
     /// This #underline(evade: false)[is less great].
     /// ```
@@ -103,12 +99,12 @@ impl Show for UnderlineNode {
 /// Add a line over text.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #overline[A line over text.]
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to add a line over.
 ///
 /// ## Category
@@ -123,8 +119,7 @@ impl OverlineNode {
     /// How to stroke the line. The text color and thickness are read from the
     /// font tables if `{auto}`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(fill: olive)
     /// #overline(
     ///   stroke: green.darken(20%),
@@ -138,8 +133,7 @@ impl OverlineNode {
     /// Position of the line relative to the baseline, read from the font tables
     /// if `{auto}`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #overline(offset: -1.2em)[
     ///   The Tale Of A Faraway Line II
     /// ]
@@ -149,8 +143,7 @@ impl OverlineNode {
 
     /// Amount that the line will be longer or shorter than its associated text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set overline(extent: 4pt)
     /// #set underline(extent: 4pt)
     /// #overline(underline[Typography Today])
@@ -161,8 +154,7 @@ impl OverlineNode {
     /// Whether the line skips sections in which it would collide with the
     /// glyphs.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #overline(
     ///   evade: false,
     ///   offset: -7.5pt,
@@ -204,12 +196,12 @@ impl Show for OverlineNode {
 /// Strike through text.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// This is #strike[not] relevant.
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to strike through.
 ///
 /// ## Category
@@ -227,8 +219,7 @@ impl StrikeNode {
     /// _Note:_ Please don't use this for real redaction as you can still
     /// copy paste the text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// This is #strike(stroke: 1.5pt + red)[very stricken through]. \
     /// This is #strike(stroke: 10pt)[redacted].
     /// ```
@@ -240,8 +231,7 @@ impl StrikeNode {
     ///
     /// This is useful if you are unhappy with the offset your font provides.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(family: "Inria Serif")
     /// This is #strike(offset: auto)[low-ish]. \
     /// This is #strike(offset: -3.5pt)[on-top].
@@ -251,8 +241,7 @@ impl StrikeNode {
 
     /// Amount that the line will be longer or shorter than its associated text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// This #strike(extent: -2pt)[skips] parts of the word.
     /// This #strike(extent: 2pt)[extends] beyond the word.
     /// ```
@@ -287,8 +276,6 @@ impl Show for StrikeNode {
 }
 
 /// Defines a line that is positioned over, under or on top of text.
-///
-/// For more details, see [`DecoNode`].
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub struct Decoration {
     pub line: DecoLine,

library/src/text/misc.rs

@@ -34,7 +34,7 @@ impl Behave for SpaceNode {
 /// lines.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// *Date:* 26.12.2022 \
 /// *Topic:* Infrastructure Test \
 /// *Severity:* High \
@@ -46,14 +46,13 @@ impl Behave for SpaceNode {
 /// break.
 ///
 /// ## Parameters
-/// - justify: bool (named)
+/// - justify: `bool` (named)
 ///   Whether to justify the line before the break.
 ///
 ///   This is useful if you found a better line break opportunity in your
 ///   justified text than Typst did.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #set par(justify: true)
 ///   #let jb = linebreak(justify: true)
 ///
@@ -98,7 +97,7 @@ impl Behave for LinebreakNode {
 /// Increases the current font weight by a given `delta`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// This is *strong.* \
 /// This is #strong[too.] \
 ///
@@ -113,7 +112,7 @@ impl Behave for LinebreakNode {
 /// function.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to strongly emphasize.
 ///
 /// ## Category
@@ -127,8 +126,7 @@ pub struct StrongNode(pub Content);
 impl StrongNode {
     /// The delta to apply on the font weight.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set strong(delta: 0)
     /// No *effect!*
     /// ```
@@ -172,13 +170,13 @@ impl Fold for Delta {
 /// # Emphasis
 /// Emphasizes content by setting it in italics.
 ///
-/// - If the current [text style](@text/style) is `{"normal"}`,
+/// - If the current [text style]($func/text.style) is `{"normal"}`,
 ///   this turns it into `{"italic"}`.
 /// - If it is already `{"italic"}` or `{"oblique"}`,
 ///   it turns it back to `{"normal"}`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// This is _emphasized._ \
 /// This is #emph[too.]
 ///
@@ -195,7 +193,7 @@ impl Fold for Delta {
 /// boundaries. To emphasize part of a word, you have to use the function.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content to emphasize.
 ///
 /// ## Category
@@ -241,14 +239,14 @@ impl Fold for Toggle {
 /// Convert text or content to lowercase.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #lower("ABC") \
 /// #lower[*My Text*] \
 /// #lower[already low]
 /// ```
 ///
 /// ## Parameters
-/// - text: ToCase (positional, required)
+/// - text: `ToCase` (positional, required)
 ///   The text to convert to lowercase.
 ///
 /// ## Category
@@ -262,14 +260,14 @@ pub fn lower(args: &mut Args) -> SourceResult<Value> {
 /// Convert text or content to uppercase.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #upper("abc") \
 /// #upper[*my text*] \
 /// #upper[ALREADY HIGH]
 /// ```
 ///
 /// ## Parameters
-/// - text: ToCase (positional, required)
+/// - text: `ToCase` (positional, required)
 ///   The text to convert to uppercase.
 ///
 /// ## Category
@@ -328,7 +326,7 @@ impl Case {
 /// smallcaps from normal letters, but this is not yet implemented.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set par(justify: true)
 /// #set text(family: "Noto Serif")
 /// #set heading(numbering: "I.")
@@ -344,7 +342,7 @@ impl Case {
 /// ```
 ///
 /// ## Parameters
-/// - text: Content (positional, required)
+/// - text: `Content` (positional, required)
 ///   The text to display to small capitals.
 ///
 /// ## Category

library/src/text/mod.rs

@@ -31,7 +31,7 @@ use crate::prelude::*;
 /// useful when passing text as an argument to another function.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set text(18pt)
 /// With a set rule.
 ///
@@ -41,7 +41,7 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - family: EcoString (positional, variadic, settable)
+/// - family: `EcoString` (positional, variadic, settable)
 ///   A prioritized sequence of font families.
 ///
 ///   When processing text, Typst tries all specified font families in order
@@ -49,8 +49,7 @@ use crate::prelude::*;
 ///   the font `Inria Serif` is preferred, but since it does not contain Arabic
 ///   glyphs, the arabic text uses `Noto Sans Arabic` instead.
 ///
-///   ### Example
+///   ```example
-///   ```
 ///   #set text(
 ///     "Inria Serif",
 ///     "Noto Sans Arabic",
@@ -61,7 +60,7 @@ use crate::prelude::*;
 ///
 ///   ```
 ///
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   Content in which all text is styled according to the other arguments.
 ///
 /// ## Category
@@ -94,8 +93,7 @@ impl TextNode {
     /// future, you will be able to instruct Typst to issue warnings so you know
     /// something is up.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(family: "Inria Serif")
     /// هذا عربي
     ///
@@ -114,11 +112,10 @@ impl TextNode {
     /// italic and oblique style is rarely observable.
     ///
     /// If you want to emphasize your text, you should do so using the
-    /// [emph](@emph) function instead. This makes it easy to adapt the style
+    /// [emph]($func/emph) function instead. This makes it easy to adapt the
-    /// later if you change your mind about how to signify the emphasis.
+    /// style later if you change your mind about how to signify the emphasis.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #text("IBM Plex Sans", style: "italic")[Italic]
     /// #text("DejaVu Sans", style: "oblique")[Oblique]
     /// ```
@@ -130,12 +127,11 @@ impl TextNode {
     /// that is closest in weight.
     ///
     /// If you want to strongly emphasize your text, you should do so using the
-    /// [strong](@strong) function instead. This makes it easy to adapt the
+    /// [strong]($func/strong) function instead. This makes it easy to adapt the
     /// style later if you change your mind about how to signify the strong
     /// emphasis.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #text(weight: "light")[Light] \
     /// #text(weight: "regular")[Regular] \
     /// #text(weight: "medium")[Medium] \
@@ -148,8 +144,7 @@ impl TextNode {
     /// `{200%}`. When the desired weight is not available, Typst selects the
     /// font from the family that is closest in stretch.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #text(stretch: 75%)[Condensed] \
     /// #text(stretch: 100%)[Normal]
     /// ```
@@ -161,8 +156,7 @@ impl TextNode {
     /// You can also give the font size itself in `em` units. Then, it is
     /// relative to the previous font size.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(size: 20pt)
     /// very #text(1.5em)[big] text
     /// ```
@@ -171,8 +165,7 @@ impl TextNode {
 
     /// The glyph fill color.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(fill: red)
     /// This text is red.
     /// ```
@@ -181,8 +174,7 @@ impl TextNode {
 
     /// The amount of space that should be added between characters.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(tracking: 1.5pt)
     /// Distant text.
     /// ```
@@ -194,8 +186,7 @@ impl TextNode {
     /// Can be given as an absolute length, but also relative to the width of
     /// the space character in the font.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(spacing: 200%)
     /// Text with distant words.
     /// ```
@@ -204,8 +195,7 @@ impl TextNode {
 
     /// An amount to shift the text baseline by.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// A #text(baseline: 3pt)[lowered]
     /// word.
     /// ```
@@ -215,8 +205,7 @@ impl TextNode {
     /// Whether certain glyphs can hang over into the margin in justified text.
     /// This can make justification visually more pleasing.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set par(justify: true)
     /// In this particular text, the
     /// justification produces a hyphen
@@ -238,8 +227,7 @@ impl TextNode {
     /// The top end of the conceptual frame around the text used for layout and
     /// positioning. This affects the size of containers that hold text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set rect(inset: 0pt)
     /// #set text(size: 20pt)
     ///
@@ -254,8 +242,7 @@ impl TextNode {
     /// The bottom end of the conceptual frame around the text used for layout
     /// and positioning. This affects the size of containers that hold text.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set rect(inset: 0pt)
     /// #set text(size: 20pt)
     ///
@@ -273,12 +260,11 @@ impl TextNode {
     ///
     /// - The text processing pipeline can make more informed choices.
     /// - Hyphenation will use the correct patterns for the language.
-    /// - [Smart quotes](@smartquote) turns into the correct quotes for the
+    /// - [Smart quotes]($func/smartquote) turns into the correct quotes for the
     ///   language.
     /// - And all other things which are language-aware.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(lang: "de")
     /// #outline()
     ///
@@ -299,20 +285,20 @@ impl TextNode {
     /// - `{rtl}`: Layout text from right to left.
     ///
     /// When writing in right-to-left scripts like Arabic or Hebrew, you should
-    /// set the [text language](@text/lang) or direction. While individual runs
+    /// set the [text language]($func/text.lang) or direction. While individual
-    /// of text are automatically layouted in the correct direction, setting the
+    /// runs of text are automatically layouted in the correct direction,
-    /// dominant direction gives the bidirectional reordering algorithm the
+    /// setting the dominant direction gives the bidirectional reordering
-    /// necessary information to correctly place punctuation and inline objects.
+    /// algorithm the necessary information to correctly place punctuation and
-    /// Furthermore, setting the direction affects the alignment values `start`
+    /// inline objects. Furthermore, setting the direction affects the alignment
-    /// and `end`, which are equivalent to `left` and `right` in `ltr` text and
+    /// values `start` and `end`, which are equivalent to `left` and `right` in
-    /// the other way around in `rtl` text.
+    /// `ltr` text and the other way around in `rtl` text.
     ///
     /// If you set this to `rtl` and experience bugs or in some way bad looking
-    /// output, please do get in touch with us through the [contact
+    /// output, please do get in touch with us through the
-    /// form](/contact) or our [Discord server](/docs/community/#discord)!
+    /// [contact form](https://typst.app/contact) or our
+    /// [Discord server]($community/#discord)!
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(dir: rtl)
     /// هذا عربي.
     /// ```
@@ -322,11 +308,10 @@ impl TextNode {
     /// Whether to hyphenate text to improve line breaking. When `{auto}`, text
     /// will be hyphenated if and only if justification is enabled.
     ///
-    /// Setting the [text language](@text/lang) ensures that the correct
+    /// Setting the [text language]($func/text.lang) ensures that the correct
     /// hyphenation patterns are used.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set par(justify: true)
     /// This text illustrates how
     /// enabling hyphenation can
@@ -348,8 +333,7 @@ impl TextNode {
     /// more natural look. Setting this to `{false}` disables kerning by turning
     /// off the OpenType `kern` font feature.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(size: 25pt)
     /// Totally
     ///
@@ -364,8 +348,7 @@ impl TextNode {
     /// Setting this to `{true}` switches to these by enabling the OpenType
     /// `salt` font feature.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(size: 20pt)
     /// 0, a, g, ß
     ///
@@ -388,8 +371,7 @@ impl TextNode {
     /// these ligatures by turning off the OpenType `liga` and `clig` font
     /// features.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(size: 20pt)
     /// A fine ligature.
     ///
@@ -409,8 +391,7 @@ impl TextNode {
     /// Which kind of numbers / figures to select. When set to `{auto}`, the
     /// default numbers for the font are used.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(20pt, "Noto Sans")
     /// #set text(number-type: "lining")
     /// Number 9.
@@ -423,8 +404,7 @@ impl TextNode {
     /// The width of numbers / figures. When set to `{auto}`, the default
     /// numbers for the font are used.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set text(20pt, "Noto Sans")
     /// #set text(number-width: "proportional")
     /// A 12 B 34. \
@@ -439,8 +419,7 @@ impl TextNode {
     /// Whether to have a slash through the zero glyph. Setting this to `{true}`
     /// enables the OpenType `zero` font feature.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// 0, #text(slashed-zero: true)[0]
     /// ```
     pub const SLASHED_ZERO: bool = false;
@@ -448,8 +427,7 @@ impl TextNode {
     /// Whether to turns numbers into fractions. Setting this to `{true}`
     /// enables the OpenType `frac` font feature.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// 1/2 \
     /// #text(fractions: true)[1/2]
     /// ```
@@ -462,8 +440,7 @@ impl TextNode {
     /// - If given a dictionary mapping to numbers, sets the features
     ///   identified by the keys to the values.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// // Enable the `frac` feature manually.
     /// #set text(features: ("frac",))
     /// 1/2

library/src/text/quotes.rs

@@ -6,14 +6,10 @@ use crate::prelude::*;
 /// A language-aware quote that reacts to its context.
 ///
 /// Automatically turns into an appropriate opening or closing quote based on
-/// the active [text language](@text/lang).
+/// the active [text language]($func/text.lang).
-///
-/// ## Syntax
-/// This function also has dedicated syntax: The normal quote characters
-/// (`'` and `"`). Typst automatically makes your quotes smart.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// "This is in quotes."
 ///
 /// #set text(lang: "de")
@@ -23,8 +19,12 @@ use crate::prelude::*;
 /// "C'est entre guillemets."
 /// ```
 ///
+/// ## Syntax
+/// This function also has dedicated syntax: The normal quote characters
+/// (`'` and `"`). Typst automatically makes your quotes smart.
+///
 /// ## Parameters
-/// - double: bool (named)
+/// - double: `bool` (named)
 ///   Whether this should be a double quote.
 ///
 /// ## Category
@@ -43,8 +43,7 @@ impl SmartQuoteNode {
     /// To disable smartness for a single quote, you can also escape it with a
     /// backslash.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set smartquote(enabled: false)
     ///
     /// These are "dumb" quotes.

library/src/text/raw.rs

@@ -23,7 +23,7 @@ use crate::prelude::*;
 /// escape sequences.
 ///
 /// ## Example
-/// ````
+/// ````example
 /// Adding `rbx` to `rcx` gives
 /// the desired result.
 ///
@@ -35,14 +35,13 @@ use crate::prelude::*;
 /// ````
 ///
 /// ## Parameters
-/// - text: EcoString (positional, required)
+/// - text: `EcoString` (positional, required)
 ///   The raw text.
 ///
 ///   You can also use raw blocks creatively to create custom syntaxes for
 ///   your automations.
 ///
-///   ### Example
+///   ````example
-///   ````
 ///   // Parse numbers in raw blocks with the
 ///   // `mydsl` tag and sum them up.
 ///   #show raw.where(lang: "mydsl"): it => {
@@ -58,11 +57,10 @@ use crate::prelude::*;
 ///   ```
 ///   ````
 ///
-/// - block: bool (named)
+/// - block: `bool` (named)
 ///   Whether the raw text is displayed as a separate block.
 ///
-///   ### Example
+///   ````example
-///   ````
 ///   // Display inline code in a small box
 ///   // that retains the correct baseline.
 ///   #show raw.where(block: false): rect.with(
@@ -107,8 +105,7 @@ impl RawNode {
     /// `{"typ"}` and `{"typc"}` tags for Typst markup and Typst code,
     /// respectively.
     ///
-    /// # Example
+    /// ````example
-    /// ````
     /// ```typ
     /// This is *Typst!*
     /// ```

library/src/text/shift.rs

@@ -10,12 +10,12 @@ use crate::prelude::*;
 /// The text is rendered smaller and its baseline is lowered.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Revenue#sub[yearly]
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The text to display in subscript.
 ///
 /// ## Category
@@ -33,8 +33,7 @@ impl SubNode {
     /// codepoints. If that fails, it falls back to rendering lowered and shrunk
     /// normal letters.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// N#sub(typographic: true)[1]
     /// N#sub(typographic: false)[1]
     /// ```
@@ -91,12 +90,12 @@ impl Show for SubNode {
 /// The text is rendered smaller and its baseline is raised.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// 1#super[st] try!
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The text to display in superscript.
 ///
 /// ## Category
@@ -114,8 +113,7 @@ impl SuperNode {
     /// superscript codepoints. If that fails, it falls back to rendering
     /// raised and shrunk normal letters.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// N#super(typographic: true)[1]
     /// N#super(typographic: false)[1]
     /// ```

library/src/visualize/image.rs

@@ -10,7 +10,7 @@ use crate::prelude::*;
 /// Supported formats are PNG, JPEG, GIF and SVG.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #align(center)[
 ///   #image("molecular.jpg", width: 80%)
 ///
@@ -20,13 +20,13 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - path: EcoString (positional, required)
+/// - path: `EcoString` (positional, required)
 ///   Path to an image file.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The width of the image.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The height of the image.
 ///
 /// ## Category

library/src/visualize/line.rs

@@ -4,24 +4,24 @@ use crate::prelude::*;
 /// A line from one point to another.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set page(height: 100pt)
 /// #line(end: (50%, 50%))
 /// ```
 ///
 /// ## Parameters
-/// - start: Axes<Rel<Length>> (named)
+/// - start: `Axes<Rel<Length>>` (named)
 ///   The start point of the line.
 ///   Must be an array of exactly two relative lengths.
 ///
-/// - end: Axes<Rel<Length>> (named)
+/// - end: `Axes<Rel<Length>>` (named)
 ///   The end point of the line.
 ///   Must be an array of exactly two relative lengths.
 ///
-/// - length: Rel<Length> (named)
+/// - length: `Rel<Length>` (named)
 ///   The line's length. Mutually exclusive with `end`.
 ///
-/// - angle: Angle (named)
+/// - angle: `Angle` (named)
 ///   The angle at which the line points away from the origin. Mutually
 ///   exclusive with `end`.
 ///
@@ -48,8 +48,7 @@ impl LineNode {
     /// - A stroke combined from color and thickness using the `+` operator as
     ///   in `{2pt + red}`.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #line(length: 100%, stroke: 2pt + red)
     /// ```
     #[property(resolve, fold)]

library/src/visualize/shape.rs

@@ -6,7 +6,7 @@ use crate::prelude::*;
 /// A rectangle with optional content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// // Without content.
 /// #rect(width: 35%, height: 30pt)
 ///
@@ -18,16 +18,16 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The content to place into the rectangle.
 ///
 ///   When this is omitted, the rectangle takes on a default size of at most
 ///   `{45pt}` by `{30pt}`.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The rectangle's width, relative to its parent container.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The rectangle's height, relative to its parent container.
 ///
 /// ## Category
@@ -44,8 +44,7 @@ impl RectNode {
     /// When setting a fill, the default stroke disappears. To create a
     /// rectangle with both fill and stroke, you have to configure both.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #rect(fill: blue)
     /// ```
     pub const FILL: Option<Paint> = None;
@@ -73,8 +72,7 @@ impl RectNode {
     ///   - `rest`: The stroke on all sides except those for which the
     ///     dictionary explicitly sets a size.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #stack(
     ///   dir: ltr,
     ///   spacing: 1fr,
@@ -104,8 +102,7 @@ impl RectNode {
     ///   - `rest`: The radii for all corners except those for which the
     ///     dictionary explicitly sets a size.
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// #set rect(stroke: 4pt)
     /// #rect(
     ///   radius: (
@@ -129,10 +126,9 @@ impl RectNode {
     /// The default value is `{5pt}`.
     ///
     /// _Note:_ When the rectangle contains text, its exact size depends on the
-    /// current [text edges](@text/top-edge).
+    /// current [text edges]($func/text.top-edge).
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// A #rect(inset: 0pt)[tight] fit.
     /// ```
     #[property(resolve, fold)]
@@ -142,10 +138,10 @@ impl RectNode {
     ///
     /// This is, for instance, useful to prevent an inline rectangle from
     /// affecting line layout. For a generalized version of the example below,
-    /// see the documentation for the [raw text's block parameter](@raw/block).
+    /// see the documentation for the
+    /// [raw text's block parameter]($func/raw.block).
     ///
-    /// # Example
+    /// ```example
-    /// ```
     /// This
     /// #rect(
     ///   fill: luma(235),
@@ -203,7 +199,7 @@ impl Inline for RectNode {}
 /// A square with optional content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// // Without content.
 /// #square(size: 40pt)
 ///
@@ -215,24 +211,24 @@ impl Inline for RectNode {}
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The content to place into the square. The square expands to fit this
 ///   content, keeping the 1-1 aspect ratio.
 ///
 ///   When this is omitted, the square takes on a default size of at most
 ///   `{30pt}`.
 ///
-/// - size: Length (named)
+/// - size: `Length` (named)
 ///   The square's side length. This is mutually exclusive with `width` and
 ///   `height`.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The square's width. This is mutually exclusive with `size` and `height`.
 ///
 ///   In contrast to `size`, this can be relative to the parent container's
 ///   width.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The square's height. This is mutually exclusive with `size` and `width`.
 ///
 ///   In contrast to `size`, this can be relative to the parent container's
@@ -247,29 +243,29 @@ pub struct SquareNode(pub Option<Content>);
 
 #[node]
 impl SquareNode {
-    /// How to fill the square. See the [rectangle's documentation](@rect/fill)
+    /// How to fill the square. See the
-    /// for more details.
+    /// [rectangle's documentation]($func/rect.fill) for more details.
     pub const FILL: Option<Paint> = None;
 
     /// How to stroke the square. See the [rectangle's
-    /// documentation](@rect/stroke) for more details.
+    /// documentation]($func/rect.stroke) for more details.
     #[property(resolve, fold)]
     pub const STROKE: Smart<Sides<Option<Option<PartialStroke>>>> = Smart::Auto;
 
     /// How much to round the square's corners. See the [rectangle's
-    /// documentation](@rect/radius) for more details.
+    /// documentation]($func/rect.radius) for more details.
     #[property(resolve, fold)]
     pub const RADIUS: Corners<Option<Rel<Length>>> = Corners::splat(Rel::zero());
 
     /// How much to pad the square's content. See the [rectangle's
-    /// documentation](@rect/inset) for more details.
+    /// documentation]($func/rect.inset) for more details.
     ///
     /// The default value is `{5pt}`.
     #[property(resolve, fold)]
     pub const INSET: Sides<Option<Rel<Length>>> = Sides::splat(Abs::pt(5.0).into());
 
     /// How much to expand the square's size without affecting the layout. See
-    /// the [rectangle's documentation](@rect/outset) for more details.
+    /// the [rectangle's documentation]($func/rect.outset) for more details.
     #[property(resolve, fold)]
     pub const OUTSET: Sides<Option<Rel<Length>>> = Sides::splat(Rel::zero());
 
@@ -326,7 +322,7 @@ impl Inline for SquareNode {}
 /// An ellipse with optional content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// // Without content.
 /// #ellipse(width: 35%, height: 30pt)
 ///
@@ -339,16 +335,16 @@ impl Inline for SquareNode {}
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The content to place into the ellipse.
 ///
 ///   When this is omitted, the ellipse takes on a default size of at most
 ///   `{45pt}` by `{30pt}`.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The ellipse's width, relative to its parent container.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The ellipse's height, relative to its parent container.
 ///
 /// ## Category
@@ -360,24 +356,24 @@ pub struct EllipseNode(pub Option<Content>);
 
 #[node]
 impl EllipseNode {
-    /// How to fill the ellipse. See the [rectangle's documentation](@rect/fill)
+    /// How to fill the ellipse. See the
-    /// for more details.
+    /// [rectangle's documentation]($func/rect.fill) for more details.
     pub const FILL: Option<Paint> = None;
 
     /// How to stroke the ellipse. See the [rectangle's
-    /// documentation](@rect/stroke) for more details.
+    /// documentation]($func/rect.stroke) for more details.
     #[property(resolve, fold)]
     pub const STROKE: Smart<Option<PartialStroke>> = Smart::Auto;
 
     /// How much to pad the ellipse's content. See the [rectangle's
-    /// documentation](@rect/inset) for more details.
+    /// documentation]($func/rect.inset) for more details.
     ///
     /// The default value is `{5pt}`.
     #[property(resolve, fold)]
     pub const INSET: Sides<Option<Rel<Length>>> = Sides::splat(Abs::pt(5.0).into());
 
     /// How much to expand the ellipse's size without affecting the layout. See
-    /// the [rectangle's documentation](@rect/outset) for more details.
+    /// the [rectangle's documentation]($func/rect.outset) for more details.
     #[property(resolve, fold)]
     pub const OUTSET: Sides<Option<Rel<Length>>> = Sides::splat(Rel::zero());
 
@@ -426,7 +422,7 @@ impl Inline for EllipseNode {}
 /// A circle with optional content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// // Without content.
 /// #circle(radius: 25pt)
 ///
@@ -439,21 +435,21 @@ impl Inline for EllipseNode {}
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional)
+/// - body: `Content` (positional)
 ///   The content to place into the circle. The circle expands to fit this
 ///   content, keeping the 1-1 aspect ratio.
 ///
-/// - radius: Length (named)
+/// - radius: `Length` (named)
 ///   The circle's radius. This is mutually exclusive with `width` and
 ///   `height`.
 ///
-/// - width: Rel<Length> (named)
+/// - width: `Rel<Length>` (named)
 ///   The circle's width. This is mutually exclusive with `radius` and `height`.
 ///
 ///   In contrast to `size`, this can be relative to the parent container's
 ///   width.
 ///
-/// - height: Rel<Length> (named)
+/// - height: `Rel<Length>` (named)
 ///   The circle's height.This is mutually exclusive with `radius` and `width`.
 ///
 ///   In contrast to `size`, this can be relative to the parent container's
@@ -468,24 +464,24 @@ pub struct CircleNode(pub Option<Content>);
 
 #[node]
 impl CircleNode {
-    /// How to fill the circle. See the [rectangle's documentation](@rect/fill)
+    /// How to fill the circle. See the
-    /// for more details.
+    /// [rectangle's documentation]($func/rect.fill) for more details.
     pub const FILL: Option<Paint> = None;
 
     /// How to stroke the circle. See the [rectangle's
-    /// documentation](@rect/stroke) for more details.
+    /// documentation]($func/rect.stroke) for more details.
     #[property(resolve, fold)]
     pub const STROKE: Smart<Option<PartialStroke>> = Smart::Auto;
 
     /// How much to pad the circle's content. See the [rectangle's
-    /// documentation](@rect/inset) for more details.
+    /// documentation]($func/rect.inset) for more details.
     ///
     /// The default value is `{5pt}`.
     #[property(resolve, fold)]
     pub const INSET: Sides<Option<Rel<Length>>> = Sides::splat(Abs::pt(5.0).into());
 
     /// How much to expand the circle's size without affecting the layout. See
-    /// the [rectangle's documentation](@rect/outset) for more details.
+    /// the [rectangle's documentation]($func/rect.outset) for more details.
     #[property(resolve, fold)]
     pub const OUTSET: Sides<Option<Rel<Length>>> = Sides::splat(Rel::zero());
 

macros/src/func.rs

@@ -16,16 +16,9 @@ pub fn func(item: syn::Item) -> Result<TokenStream> {
     let display = display.trim();
 
     let mut docs = docs[first.len()..].to_string();
-    let example = example(&mut docs, 2);
     let (params, returns) = params(&mut docs)?;
-    let syntax = quote_option(section(&mut docs, "Syntax", 2));
     let category = section(&mut docs, "Category", 2).expect("missing category");
-    let example = quote_option(example);
-
     let docs = docs.trim();
-    if docs.contains("# ") {
-        bail!(item, "unrecognized heading");
-    }
 
     let info = quote! {
         ::typst::model::FuncInfo {
@@ -33,8 +26,6 @@ pub fn func(item: syn::Item) -> Result<TokenStream> {
             display: #display,
             category: #category,
             docs: #docs,
-            example: #example,
-            syntax: #syntax,
             params: ::std::vec![#(#params),*],
             returns: ::std::vec![#(#returns),*]
         }
@@ -108,17 +99,6 @@ pub fn section(docs: &mut String, title: &str, level: usize) -> Option<String> {
     Some(section)
 }
 
-/// Parse the example section.
-pub fn example(docs: &mut String, level: usize) -> Option<String> {
-    let section = section(docs, "Example", level)?;
-    let mut s = unscanny::Scanner::new(&section);
-    let count = s.eat_while('`').len();
-    let term = "`".repeat(count);
-    let text = s.eat_until(term.as_str()).trim();
-    s.expect(term.as_str());
-    Some(text.into())
-}
-
 /// Parse the parameter section.
 fn params(docs: &mut String) -> Result<(Vec<TokenStream>, Vec<String>)> {
     let Some(section) = section(docs, "Parameters", 2) else {
@@ -151,7 +131,9 @@ fn params(docs: &mut String) -> Result<(Vec<TokenStream>, Vec<String>)> {
             continue;
         }
 
-        let ty: syn::Type = syn::parse_str(s.eat_until(char::is_whitespace))?;
+        s.expect('`');
+        let ty: syn::Type = syn::parse_str(s.eat_until('`'))?;
+        s.expect('`');
         s.eat_whitespace();
         s.expect('(');
 
@@ -176,15 +158,13 @@ fn params(docs: &mut String) -> Result<(Vec<TokenStream>, Vec<String>)> {
 
         s.expect(')');
 
-        let mut docs = dedent(s.eat_until("\n-").trim());
+        let docs = dedent(s.eat_until("\n-").trim());
-        let example = quote_option(example(&mut docs, 3));
         let docs = docs.trim();
 
         infos.push(quote! {
             ::typst::model::ParamInfo {
                 name: #name,
                 docs: #docs,
-                example: #example,
                 cast: <#ty as ::typst::model::Cast<
                     ::typst::syntax::Spanned<::typst::model::Value>
                 >>::describe(),

macros/src/lib.rs

@@ -26,7 +26,7 @@ mod symbols;
 
 use proc_macro::TokenStream as BoundaryStream;
 use proc_macro2::{TokenStream, TokenTree};
-use quote::{quote, quote_spanned, ToTokens};
+use quote::{quote, quote_spanned};
 use syn::{parse_quote, Ident, Result};
 
 /// Implement `FuncType` for a type or function.
@@ -105,11 +105,3 @@ fn dedent(text: &str) -> String {
         .collect::<Vec<_>>()
         .join("\n")
 }
-
-/// Quote an optional value.
-fn quote_option<T: ToTokens>(option: Option<T>) -> TokenStream {
-    match option {
-        Some(value) => quote! { Some(#value) },
-        None => quote! { None },
-    }
-}

macros/src/node.rs

@@ -336,15 +336,13 @@ fn create_node_properties_func(node: &Node) -> syn::ImplItemMethod {
         let value_ty = &property.value_ty;
         let shorthand = matches!(property.shorthand, Some(Shorthand::Positional));
 
-        let mut docs = documentation(&property.attrs);
+        let docs = documentation(&property.attrs);
-        let example = quote_option(super::func::example(&mut docs, 1));
         let docs = docs.trim();
 
         quote! {
             ::typst::model::ParamInfo {
                 name: #name,
                 docs: #docs,
-                example: #example,
                 cast: <#value_ty as ::typst::model::Cast<
                     ::typst::syntax::Spanned<::typst::model::Value>
                 >>::describe(),

src/geom/ratio.rs

@@ -3,7 +3,7 @@ use super::*;
 /// A ratio of a whole.
 ///
 /// _Note_: `50%` is represented as `0.5` here, but stored as `50.0` in the
-/// corresponding [literal](crate::syntax::ast::LitKind::Numeric).
+/// corresponding [literal](crate::syntax::ast::Numeric).
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct Ratio(Scalar);
 

src/ide/highlight.rs

@@ -1,6 +1,6 @@
 use crate::syntax::{ast, LinkedNode, SyntaxKind, SyntaxNode};
 
-/// Syntax highlighting tag.
+/// A syntax highlighting tag.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
 pub enum Tag {
     /// A line or block comment.

src/lib.rs

@@ -1,22 +1,25 @@
 //! The compiler for the _Typst_ markup language.
 //!
 //! # Steps
-//! - **Parsing:** The compiler first transforms a plain string into an
+//! - **Parsing:**
-//!   [iterator of tokens][tokens]. This token stream is [parsed] into a [syntax
+//!   The compiler first transforms a plain string into an iterator of [tokens].
-//!   tree]. The tree itself is untyped, but the [AST] module provides a typed
+//!   This token stream is [parsed] into a [syntax tree]. The tree itself is
-//!   layer over it.
+//!   untyped, but the [AST] module provides a typed layer over it.
-//! - **Evaluation:** The next step is to [evaluate] the markup. This produces a
+//! - **Evaluation:**
-//!   [module], consisting of a scope of values that were exported by the code
+//!   The next step is to [evaluate] the markup. This produces a [module],
-//!   and [content], a hierarchical, styled representation of what was written
+//!   consisting of a scope of values that were exported by the code and
-//!   in the source file. The nodes of the content tree are well structured and
+//!   [content], a hierarchical, styled representation of what was written in
+//!   the source file. The nodes of the content tree are well structured and
 //!   order-independent and thus much better suited for further processing than
 //!   the raw markup.
-//! - **Typesetting:** Next, the content is [typeset] into a [document]
+//! - **Typesetting:**
-//!   containing one [frame] per page with elements and fixed positions.
+//!   Next, the content is [typeset] into a [document] containing one [frame]
-//! - **Exporting:** These frames can finally be exported into an output format
+//!   per page with elements and fixed positions.
-//!   (currently supported are [PDF] and [raster images]).
+//! - **Exporting:**
+//!   These frames can finally be exported into an output format (currently
+//!   supported are [PDF] and [raster images]).
 //!
-//! [tokens]: syntax::Tokens
+//! [tokens]: syntax::SyntaxKind
 //! [parsed]: syntax::parse
 //! [syntax tree]: syntax::SyntaxNode
 //! [AST]: syntax::ast

src/model/func.rs

@@ -226,18 +226,14 @@ pub struct FuncInfo {
     pub name: &'static str,
     /// The display name of the function.
     pub display: &'static str,
-    /// Which category the function is part of.
-    pub category: &'static str,
     /// Documentation for the function.
     pub docs: &'static str,
-    /// The source code of an example, if any.
-    pub example: Option<&'static str>,
-    /// Documentation about this function's syntax, if it has syntax.
-    pub syntax: Option<&'static str>,
     /// Details about the function's parameters.
     pub params: Vec<ParamInfo>,
     /// Valid types for the return value.
     pub returns: Vec<&'static str>,
+    /// Which category the function is part of.
+    pub category: &'static str,
 }
 
 impl FuncInfo {
@@ -254,8 +250,6 @@ pub struct ParamInfo {
     pub name: &'static str,
     /// Documentation for the parameter.
     pub docs: &'static str,
-    /// The source code of an example, if any.
-    pub example: Option<&'static str>,
     /// Valid values for the parameter.
     pub cast: CastInfo,
     /// Is the parameter positional?

src/model/symbol.rs

@@ -6,7 +6,6 @@ use std::sync::Arc;
 use crate::diag::StrResult;
 use crate::util::EcoString;
 
-/// Define a list of symbols.
 #[doc(inline)]
 pub use typst_macros::symbols;
 
@@ -169,8 +168,6 @@ fn contained(modifiers: &str, m: &str) -> bool {
 }
 
 /// Normalize an accent to a combining one.
-///
-/// https://www.w3.org/TR/mathml-core/#combining-character-equivalences
 pub fn combining_accent(c: char) -> Option<char> {
     Some(match c {
         '\u{0300}' | '`' => '\u{0300}',

src/util/mod.rs

@@ -37,7 +37,7 @@ where
 }
 
 /// Calculate a 128-bit siphash of a value.
-pub fn hash128<T: Hash>(value: &T) -> u128 {
+pub fn hash128<T: Hash + ?Sized>(value: &T) -> u128 {
     let mut state = SipHasher::new();
     value.hash(&mut state);
     state.finish128().as_u128()