From d4be7c4ca54ce1907ce5f7af8a603cf3f4c5a42f Mon Sep 17 00:00:00 2001
From: Andrew Voynov <37143421+Andrew15-5@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:00:51 +0300
Subject: [PATCH] Add page reference customization example (#6480)

Co-authored-by: Laurenz <laurmaedje@gmail.com>
---
 crates/typst-library/src/model/reference.rs | 30 +++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/crates/typst-library/src/model/reference.rs b/crates/typst-library/src/model/reference.rs
index 6fddc56ca..17f93b7c4 100644
--- a/crates/typst-library/src/model/reference.rs
+++ b/crates/typst-library/src/model/reference.rs
@@ -79,6 +79,36 @@ use crate::text::TextElem;
 /// reference: `[@intro[Chapter]]`.
 ///
 /// # Customization
+/// When you only ever need to reference pages of a figure/table/heading/etc. in
+/// a document, the default `form` field value can be changed to `{"page"}` with
+/// a set rule. If you prefer a short "p." supplement over "page", the
+/// [`page.supplement`]($page.supplement) field can be used for changing this:
+///
+/// ```example
+/// #set page(
+///   numbering: "1",
+///   supplement: "p.",
+/// >>> margin: (bottom: 3em),
+/// >>> footer-descent: 1.25em,
+/// )
+/// #set ref(form: "page")
+///
+/// #figure(
+///   stack(
+///     dir: ltr,
+///     spacing: 1em,
+///     circle(),
+///     square(),
+///   ),
+///   caption: [Shapes],
+/// ) <shapes>
+///
+/// #pagebreak()
+///
+/// See @shapes for examples
+/// of different shapes.
+/// ```
+///
 /// If you write a show rule for references, you can access the referenced
 /// element through the `element` field of the reference. The `element` may
 /// be `{none}` even if it exists if Typst hasn't discovered it yet, so you