From 87c56865606e027f552a4dbc800c6851b0d0b821 Mon Sep 17 00:00:00 2001
From: Andrew Voynov <37143421+Andrew15-5@users.noreply.github.com>
Date: Tue, 24 Jun 2025 13:22:55 +0300
Subject: [PATCH] Add docs for `std` module (#6407)

Co-authored-by: Laurenz <laurmaedje@gmail.com>
---
 crates/typst-library/src/lib.rs |  2 +-
 docs/reference/groups.yml       | 53 +++++++++++++++++++++++++++++++++
 docs/src/lib.rs                 |  2 +-
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/crates/typst-library/src/lib.rs b/crates/typst-library/src/lib.rs
index c39024f71..fa7977888 100644
--- a/crates/typst-library/src/lib.rs
+++ b/crates/typst-library/src/lib.rs
@@ -148,7 +148,7 @@ pub struct Library {
     /// The default style properties (for page size, font selection, and
     /// everything else configurable via set and show rules).
     pub styles: Styles,
-    /// The standard library as a value. Used to provide the `std` variable.
+    /// The standard library as a value. Used to provide the `std` module.
     pub std: Binding,
     /// In-development features that were enabled.
     pub features: Features,
diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml
index e5aa7e999..c7e3d9964 100644
--- a/docs/reference/groups.yml
+++ b/docs/reference/groups.yml
@@ -137,6 +137,59 @@
     In addition to the functions listed below, the `calc` module also defines
     the constants `pi`, `tau`, `e`, and `inf`.
 
+- name: std
+  title: Standard library
+  category: foundations
+  path: ["std"]
+  details: |
+    A module that contains all globally accessible items.
+
+    # Using "shadowed" definitions
+    The `std` module is useful whenever you overrode a name from the global
+    scope (this is called _shadowing_). For instance, you might have used the
+    name `text` for a parameter. To still access the `text` element, write
+    `std.text`.
+
+    ```example
+    >>> #set page(margin: (left: 3em))
+    #let par = [My special paragraph.]
+    #let special(text) = {
+      set std.text(style: "italic")
+      set std.par.line(numbering: "1")
+      text
+    }
+
+    #special(par)
+
+    #lorem(10)
+    ```
+
+    # Conditional access
+    You can also use this in combination with the [dictionary
+    constructor]($dictionary) to conditionally access global definitions. This
+    can, for instance, be useful to use new or experimental functionality when
+    it is available, while falling back to an alternative implementation if
+    used on an older Typst version. In particular, this allows us to create
+    [polyfills](https://en.wikipedia.org/wiki/Polyfill_(programming)).
+
+    This can be as simple as creating an alias to prevent warning messages, for
+    example, conditionally using `pattern` in Typst version 0.12, but using
+    [`tiling`] in newer versions. Since the parameters accepted by the `tiling`
+    function match those of the older `pattern` function, using the `tiling`
+    function when available and falling back to `pattern` otherwise will unify
+    the usage across all versions. Note that, when creating a polyfill,
+    [`sys.version`]($category/foundations/sys) can also be very useful.
+
+    ```typ
+    #let tiling = if "tiling" in dictionary(std) {
+      tiling
+    } else {
+      pattern
+    }
+
+    ...
+    ```
+
 - name: sys
   title: System
   category: foundations
diff --git a/docs/src/lib.rs b/docs/src/lib.rs
index b81f0dc66..9bd21c2e8 100644
--- a/docs/src/lib.rs
+++ b/docs/src/lib.rs
@@ -37,7 +37,7 @@ static GROUPS: LazyLock<Vec<GroupData>> = LazyLock::new(|| {
     let mut groups: Vec<GroupData> =
         yaml::from_str(load!("reference/groups.yml")).unwrap();
     for group in &mut groups {
-        if group.filter.is_empty() {
+        if group.filter.is_empty() && group.name != "std" {
             group.filter = group
                 .module()
                 .scope()