Clarify syntactical difference in `label` function docs (#4957)

1 files changed, 10 insertions, 0 deletions

diff --git a/crates/typst/src/foundations/label.rs b/crates/typst/src/foundations/label.rs
index 8f15d317..314fc8a9 100644
--- a/crates/typst/src/foundations/label.rs
+++ b/crates/typst/src/foundations/label.rs
@@ -29,6 +29,16 @@ use crate::utils::PicoStr;
 /// its name in angle brackets. This works both in markup and code. A label's
 /// name can contain letters, numbers, `_`, `-`, `:`, and `.`.
 ///
+/// Note that there is a syntactical difference when using the dedicated syntax
+/// for this function. In the code below, the `[<a>]` terminates the heading and
+/// thus attaches to the heading itself, whereas the `[#label("b")]` is part of
+/// the heading and thus attaches to the heading's text.
+///
+/// ```typ
+/// = Intro <a>         // Equivalent to `#heading[Intro] <a>`.
+/// = Concl #label("b") // Equivalent to `#heading[Concl #label("b")]`.
+/// ```
+///
 /// Currently, labels can only be attached to elements in markup mode, not in
 /// code mode. This might change in the future.
 #[ty(scope, cast)]