Docs: precise how to add new `.order-*` classes in 'Layout > Columns' (#40821)

Co-authored-by: Tobi <TobiGr@users.noreply.github.com>
Co-authored-by: Louis-Maxime Piton <louismaxime.piton@orange.com>

diff --git a/site/content/docs/5.3/layout/columns.md b/site/content/docs/5.3/layout/columns.md
index e6f5255631058100711efeded4ad9e1a76a4ed36..dc7f72768f5a9f1f87a31e91ec422da0a32e87c0 100644 (file)
--- a/site/content/docs/5.3/layout/columns.md
+++ b/site/content/docs/5.3/layout/columns.md
@@ -203,7 +203,7 @@ You may also apply this break at specific breakpoints with our [responsive displ
 
 ### Order classes
 
-Use `.order-` classes for controlling the **visual order** of your content. These classes are responsive, so you can set the `order` by breakpoint (e.g., `.order-1.order-md-2`). Includes support for `1` through `5` across all six grid tiers. If you need more `.order-*` classes, you can modify the default number via Sass variable.
+Use `.order-` classes for controlling the **visual order** of your content. These classes are responsive, so you can set the `order` by breakpoint (e.g., `.order-1.order-md-2`). Includes support for `1` through `5` across all six grid tiers.
 
 {{< example class="bd-example-row" >}}
 <div class="container text-center">
@@ -239,6 +239,28 @@ There are also responsive `.order-first` and `.order-last` classes that change t
 </div>
 {{< /example >}}
 
+If you need more `.order-*` classes, you can add new ones by modifying our `$utilities` Sass map. [Read our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) or [our Modify utilities docs]({{< docsref "/utilities/api#modify-utilities" >}}) for details.
+
+```scss
+$utilities: map-merge(
+  $utilities,
+  (
+    "order": map-merge(
+      map-get($utilities, "order"),
+      (
+        values: map-merge(
+          map-get(map-get($utilities, "order"), "values"),
+          (
+            6: 6, // Add a new `.order-{breakpoint}-6` utility
+            last: 7 // Change the `.order-{breakpoint}-last` utility to use the next number
+          )
+        ),
+      ),
+    ),
+  )
+);
+```
+
 ### Offsetting columns
 
 You can offset grid columns in two ways: our responsive `.offset-` grid classes and our [margin utilities]({{< docsref "/utilities/spacing" >}}). Grid classes are sized to match columns while margins are more useful for quick layouts where the width of the offset is variable.