Better documentation outlines

18 files changed, 30 insertions, 29 deletions

diff --git a/library/src/layout/align.rs b/library/src/layout/align.rs
index b8f7a086..4c9beb63 100644
--- a/library/src/layout/align.rs
+++ b/library/src/layout/align.rs
@@ -2,7 +2,7 @@ use crate::prelude::*;
 
 /// Align content horizontally and vertically.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 ///
diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs
index 2a587907..06e6a7e0 100644
--- a/library/src/layout/columns.rs
+++ b/library/src/layout/columns.rs
@@ -9,7 +9,7 @@ use crate::text::TextElem;
 /// height on the page. The columns function can break across pages if
 /// necessary.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// = Towards Advanced Deep Learning
 ///
@@ -132,7 +132,7 @@ impl Layout for ColumnsElem {
 /// 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 { #example }
 /// ```example
 /// #set page(columns: 2)
 /// Preliminary findings from our
diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs
index ae6a094c..04c58075 100644
--- a/library/src/layout/container.rs
+++ b/library/src/layout/container.rs
@@ -9,7 +9,7 @@ use crate::prelude::*;
 /// elements into a paragraph. Boxes take the size of their contents by default
 /// but can also be sized explicitly.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Refer to the docs
 /// #box(
@@ -170,7 +170,7 @@ impl Layout for BoxElem {
 /// Such a container can be used to separate content, size it and give it a
 /// background or border.
 ///
-/// ## Examples
+/// ## Examples { #examples }
 /// With a block, you can give a background to content while still allowing it
 /// to break across multiple pages.
 /// ```example
diff --git a/library/src/layout/enum.rs b/library/src/layout/enum.rs
index 0a11a751..f7117574 100644
--- a/library/src/layout/enum.rs
+++ b/library/src/layout/enum.rs
@@ -11,7 +11,7 @@ use super::GridLayouter;
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Automatically numbered:
 /// + Preparations
@@ -47,7 +47,7 @@ use super::GridLayouter;
 /// )
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This functions also has dedicated syntax:
 ///
 /// - Starting a line with a plus sign creates an automatically numbered
diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs
index 1e4bf40b..3c299eb0 100644
--- a/library/src/layout/grid.rs
+++ b/library/src/layout/grid.rs
@@ -34,7 +34,7 @@ use super::Sizing;
 /// instead of an array. For example, `columns:` `{3}` is equivalent to
 /// `columns:` `{(auto, auto, auto)}`.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set text(10pt, style: "italic")
 /// #let cell = rect.with(
diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs
index a65616a0..7c954401 100644
--- a/library/src/layout/hide.rs
+++ b/library/src/layout/hide.rs
@@ -7,7 +7,7 @@ use crate::prelude::*;
 /// content. It may also be useful to redact content because its arguments are
 /// not included in the output.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Hello Jane \
 /// #hide[Hello] Joe
diff --git a/library/src/layout/list.rs b/library/src/layout/list.rs
index 25783d84..75fc7c3a 100644
--- a/library/src/layout/list.rs
+++ b/library/src/layout/list.rs
@@ -9,7 +9,7 @@ use super::GridLayouter;
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// - *Content*
 ///   - Text
@@ -28,7 +28,7 @@ use super::GridLayouter;
 ///   )
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #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
diff --git a/library/src/layout/measure.rs b/library/src/layout/measure.rs
index 473bf5c6..c7a19243 100644
--- a/library/src/layout/measure.rs
+++ b/library/src/layout/measure.rs
@@ -8,6 +8,7 @@ use crate::prelude::*;
 /// If you want to measure in the current layout dimensions, you can combined
 /// `measure` and [`layout`]($func/layout).
 ///
+/// # Example { #example }
 /// The same content can have a different size depending on the styles that
 /// are active when it is layouted. For example, in the example below
 /// `[#content]` is of course bigger when we increase the font size.
diff --git a/library/src/layout/pad.rs b/library/src/layout/pad.rs
index a4e79e36..c7f9ead8 100644
--- a/library/src/layout/pad.rs
+++ b/library/src/layout/pad.rs
@@ -6,7 +6,7 @@ use crate::prelude::*;
 /// for each side individually, or for all sides at once by specifying a
 /// positional argument.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 ///
diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs
index b9d7b03d..cb0ed7dc 100644
--- a/library/src/layout/page.rs
+++ b/library/src/layout/page.rs
@@ -14,7 +14,7 @@ use crate::prelude::*;
 /// Pages can be set to use `{auto}` as their width or height. In this case,
 /// the pages will grow to fit their content on the respective axis.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// >>> #set page(margin: auto)
 /// #set page("us-letter")
@@ -415,7 +415,7 @@ impl PageElem {
 ///
 /// Must not be used inside any containers.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// The next page contains
 /// more details on compound theory.
diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs
index f87b23d8..f8df63f4 100644
--- a/library/src/layout/par.rs
+++ b/library/src/layout/par.rs
@@ -18,7 +18,7 @@ use crate::text::{
 /// properties, it can also be used to explicitly render its argument onto a
 /// paragraph of its own.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set par(first-line-indent: 1em, justify: true)
 /// #show par: set block(spacing: 0.65em)
@@ -203,7 +203,7 @@ pub enum Linebreaks {
 /// [for loops]($scripting/#loops). Multiple consecutive
 /// paragraph breaks collapse into a single one.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #for i in range(3) {
 ///   [Blind text #i: ]
@@ -212,7 +212,7 @@ pub enum Linebreaks {
 /// }
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// Instead of calling this function, you can insert a blank line into your
 /// markup to create a paragraph break.
 ///
diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs
index 2a671628..215eb5e1 100644
--- a/library/src/layout/place.rs
+++ b/library/src/layout/place.rs
@@ -7,7 +7,7 @@ use crate::prelude::*;
 /// other content in the container. Page margins will be respected.
 ///
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set page(height: 60pt)
 /// Hello, world!
diff --git a/library/src/layout/repeat.rs b/library/src/layout/repeat.rs
index 384995a4..646eb991 100644
--- a/library/src/layout/repeat.rs
+++ b/library/src/layout/repeat.rs
@@ -12,7 +12,7 @@ use super::AlignElem;
 /// Errors if there no bounds on the available space, as it would create
 /// infinite content.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// Sign on the dotted line:
 /// #box(width: 1fr, repeat[.])
diff --git a/library/src/layout/spacing.rs b/library/src/layout/spacing.rs
index 9253c497..42d2b443 100644
--- a/library/src/layout/spacing.rs
+++ b/library/src/layout/spacing.rs
@@ -8,14 +8,14 @@ use crate::prelude::*;
 /// remaining space on the line is distributed among all fractional spacings
 /// according to their relative fractions.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// First #h(1cm) Second \
 /// First #h(30%) Second \
 /// First #h(2fr) Second #h(1fr) Third
 /// ```
 ///
-/// ## Mathematical Spacing
+/// ## Mathematical Spacing { #math-spacing }
 /// In [mathematical formulas]($category/math), you can additionally use these
 /// constants to add spacing between elements: `thin`, `med`, `thick`, `quad`.
 ///
@@ -68,7 +68,7 @@ impl Behave for HElem {
 /// the remaining space on the page is distributed among all fractional spacings
 /// according to their relative fractions.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #grid(
 ///   rows: 3cm,
diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs
index 80145567..2ce2cc28 100644
--- a/library/src/layout/stack.rs
+++ b/library/src/layout/stack.rs
@@ -6,7 +6,7 @@ use crate::prelude::*;
 /// The stack places a list of items along an axis, with optional spacing
 /// between each item.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #stack(
 ///   dir: ttb,
diff --git a/library/src/layout/table.rs b/library/src/layout/table.rs
index 9cd18b56..bb24bd7c 100644
--- a/library/src/layout/table.rs
+++ b/library/src/layout/table.rs
@@ -13,7 +13,7 @@ use crate::prelude::*;
 /// To give a table a caption and make it [referenceable]($func/ref), put it
 /// into a [figure]($func/figure).
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #table(
 ///   columns: (1fr, auto, auto),
diff --git a/library/src/layout/terms.rs b/library/src/layout/terms.rs
index 073b6ee2..43127d97 100644
--- a/library/src/layout/terms.rs
+++ b/library/src/layout/terms.rs
@@ -8,14 +8,14 @@ use crate::prelude::*;
 /// descriptions span over multiple lines, they use hanging indent to
 /// communicate the visual hierarchy.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// / Ligature: A merged glyph.
 /// / Kerning: A spacing adjustment
 ///   between two adjacent letters.
 /// ```
 ///
-/// ## Syntax
+/// ## Syntax { #syntax }
 /// This function also has dedicated syntax: Starting a line with a slash,
 /// followed by a term, a colon and a description creates a term list item.
 ///
diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs
index 2fb9c191..e3622ac5 100644
--- a/library/src/layout/transform.rs
+++ b/library/src/layout/transform.rs
@@ -8,7 +8,7 @@ use crate::prelude::*;
 /// it at the original positions. Containers will still be sized as if the content
 /// was not moved.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #rect(inset: 0pt, move(
 ///   dx: 6pt, dy: 6pt,
@@ -58,7 +58,7 @@ impl Layout for MoveElem {
 /// Rotate an element by a given angle. The layout will act as if the element
 /// was not rotated.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #stack(
 ///   dir: ltr,
@@ -131,7 +131,7 @@ impl Layout for RotateElem {
 /// affecting the layout.
 ///
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
 /// #set align(center)
 /// #scale(x: -100%)[This is mirrored.]