From 77db88eb98f08b707c6f0a4cee9ac9b99bb71a38 Mon Sep 17 00:00:00 2001
From: "Y.D.X." <73375426+YDX-2147483647@users.noreply.github.com>
Date: Thu, 24 Jul 2025 20:10:55 +0800
Subject: [PATCH] Document that a `where` selector is needed to update figure
 counters

Resolves #6641

It was documented in `figure.counter`, but that field is synthesized and not visible in docs.
https://docs.rs/typst-library/0.13.1/typst_library/model/struct.FigureElem.html#method.counter
---
 .../src/introspection/counter.rs              |  2 ++
 crates/typst-library/src/model/figure.rs      | 35 +++++++++++++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/crates/typst-library/src/introspection/counter.rs b/crates/typst-library/src/introspection/counter.rs
index f6083303d..a7b0d500b 100644
--- a/crates/typst-library/src/introspection/counter.rs
+++ b/crates/typst-library/src/introspection/counter.rs
@@ -415,6 +415,8 @@ impl Counter {
         /// - If it is a [selector], counts through elements that matches with the
         ///   selector. For example,
         ///   - provide an element function: counts elements of that type,
+        ///   - provide a [`where`]($function.where) selector:
+        ///     counts a type of elements with specific fields,
         ///   - provide a [`{<label>}`]($label): counts elements with that label.
         key: CounterKey,
     ) -> Counter {
diff --git a/crates/typst-library/src/model/figure.rs b/crates/typst-library/src/model/figure.rs
index daab37e44..a3fec123f 100644
--- a/crates/typst-library/src/model/figure.rs
+++ b/crates/typst-library/src/model/figure.rs
@@ -189,6 +189,37 @@ pub struct FigureElem {
     ///   supplement: [Atom],
     /// )
     /// ```
+    ///
+    /// If you want to modify a counter to skip a number or reset the counter,
+    /// you can access the [counter] of each kind of figures from
+    /// a [`where`]($function.where) selector:
+    ///
+    /// - For [tables]($table): `{counter(figure.where(kind: table))}`
+    /// - For [images]($image): `{counter(figure.where(kind: image))}`
+    /// - For a custom kind: `{counter(figure.where(kind: kind))}`
+    ///
+    /// ```example
+    /// #figure(
+    ///   table(columns: 2, $n$, $1$),
+    ///   caption: [The first table.],
+    /// )
+    ///
+    /// #counter(figure.where(kind: table)).update(41)
+    ///
+    /// #figure(
+    ///   table(columns: 2, $n$, $42$),
+    ///   caption: [Jumped to the 42nd table.],
+    /// )
+    ///
+    /// #figure(
+    ///   rect[Image],
+    ///   caption: [And it doesn't affect images.],
+    /// )
+    /// ```
+    ///
+    /// There is also a convenience field called `counter` to simplify general
+    /// [show rules]($styling/#show-rules). There is an example
+    /// [show rule that customizes `figure.caption`]($figure.caption.body) below.
     pub kind: Smart<FigureKind>,
 
     /// The figure's supplement.
@@ -228,8 +259,8 @@ pub struct FigureElem {
     /// Convenience field to get access to the counter for this figure.
     ///
     /// The counter only depends on the `kind`:
-    /// - For (tables)[@table]: `{counter(figure.where(kind: table))}`
-    /// - For (images)[@image]: `{counter(figure.where(kind: image))}`
+    /// - For [tables]($table): `{counter(figure.where(kind: table))}`
+    /// - For [images]($image): `{counter(figure.where(kind: image))}`
     /// - For a custom kind: `{counter(figure.where(kind: kind))}`
     ///
     /// These are the counters you'll need to modify if you want to skip a