Reorganise headings in utilities page and minor edits

diff --git a/site/content/docs/5.3/utilities/api.md b/site/content/docs/5.3/utilities/api.md
index 044bd40c968f8a416d98a00aed6cc61bd0c99fe8..3a3167a34109b0657f91b51ddad8250b40267ee9 100644 (file)
--- a/site/content/docs/5.3/utilities/api.md
+++ b/site/content/docs/5.3/utilities/api.md
@@ -369,16 +369,27 @@ All utilities generated by the API include `!important` to ensure they override
 Now that you're familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities. There are two ways you can do this:
 
 1. If you only need to override our default utilities or add new ones, we'll merge your `$utilities` variable with ours
-2. If you require more fine grained control, we provide mixins to let you update our default utilities configuration.
+2. If you require more fine-grained control, we provide mixins to let you update our default utilities configuration.
 
-You may also want to refer to some of the utilities configuration in your Sass code, for which we provide some handy functions.
+You may also want to refer to parts of the utilities configuration in your Sass code, the value of a specific utility especially. We provide getter functions to access those.
 
 ### Adding or overriding utilities
 
-Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:
+If your code declares a `$utilities` map before importing `bootstrap/scss/utilities`,
+it'll get merged with ours:
+
+- add new keys to create your own utilities
+- override existing utilities by using the same key
 
 ```scss
 $utilities: (
+  // Adds a new font-variant utility
+  "font-variant": (
+    class: fv,
+    property: font-variant,
+    values: tabular-nums small-caps,
+  ),
+  // Redefines the overflow utility
   "overflow": (
     responsive: true,
     property: overflow,
@@ -487,9 +498,40 @@ replacing the `values` option can be a bit of a burden to maintain.
 @import 'bootstrap/scss/utilities/api';
 ```
 
-#### Practical examples
+### Getting utility values and options
 
-##### Enable responsive
+The `utilities-get-value` function let your grab a specific value of a utility.
+This can help you run some computations with it, either in Sass or with `calc()`.
+It also lets you access values that can be tweaked by other utilities,
+(like how `bg`, `text` and `border` can be tweaked by `bg-opacity`, `text-opacity` or `border-opacity` respectively).
+
+```scss
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/variables-dark";
+@import "bootstrap/scss/maps";
+@import "bootstrap/scss/mixins";
+
+@import "bootstrap/scss/utilities";
+
+// The box will be configurable with the bg-opacity and text-opacity classes
+.box {
+  border: utilities-get-value(border, null);
+  padding: map-get($spacers, 3);
+  background: utilities-get-value(background-color, body);
+  color: utilities-get-value(color, body);
+}
+```
+
+This is likely the function you'll use the most, but you can also:
+
+- access all the values of a utility with `utilities-get-values`, which will always return a map to simplify their processing
+- access a specific option with `utilities-get-option`
+- or even all the options with `utilities-get-options`
+
+## Practical examples
+
+### Enable responsive
 
 You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the `border` classes responsive:
 
@@ -507,7 +549,39 @@ You can enable responsive classes for an existing set of utilities that are not
 @import "bootstrap/scss/utilities/api";
 ```
 
-##### Rename utilities
+This will now generate responsive variations of `.border` and `.border-0` for each breakpoint. Your generated CSS will look like this:
+
+```css
+.border { ... }
+.border-0 { ... }
+
+@media (min-width: 576px) {
+  .border-sm { ... }
+  .border-sm-0 { ... }
+}
+
+@media (min-width: 768px) {
+  .border-md { ... }
+  .border-md-0 { ... }
+}
+
+@media (min-width: 992px) {
+  .border-lg { ... }
+  .border-lg-0 { ... }
+}
+
+@media (min-width: 1200px) {
+  .border-xl { ... }
+  .border-xl-0 { ... }
+}
+
+@media (min-width: 1400px) {
+  .border-xxl { ... }
+  .border-xxl-0 { ... }
+}
+```
+
+### Rename utilities
 
 Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`:
 
@@ -525,7 +599,7 @@ Missing v4 utilities, or used to another naming convention? The utilities API ca
 @import "bootstrap/scss/utilities/api";
 ```
 
-##### Remove utility in RTL
+### Remove utility in RTL
 
 Some edge cases make [RTL styling difficult](https://rtlstyling.com/posts/rtl-styling#common-things-that-might-not-work-for-rtl), such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the `rtl` option to `false`:
 
@@ -555,34 +629,3 @@ Output:
 ```
 
 This doesn't output anything in RTL, thanks to [the RTLCSS `remove` control directive](https://rtlcss.com/learn/usage-guide/control-directives/#remove).
-
-### Referring to the utilities configuration
-
-The `utilities-get-value` function let your grab a specific value of a utility.
-This can help you run some computations with it, either in Sass or with `calc()`.
-It also lets you access values that can be tweaked by other utilities,
-(like how `bg`, `text` and `border` can be tweaked by `bg-opacity`, `text-opacity` or `border-opacity` respectively).
-
-```scss
-@import "bootstrap/scss/functions";
-@import "bootstrap/scss/variables";
-@import "bootstrap/scss/variables-dark";
-@import "bootstrap/scss/maps";
-@import "bootstrap/scss/mixins";
-
-@import "bootstrap/scss/utilities";
-
-// The box will be configurable with the bg-opacity and text-opacity classes
-.box {
-  border: utilities-get-value(border, null);
-  padding: map-get($spacers, 3);
-  background: utilities-get-value(background-color, body);
-  color: utilities-get-value(color, body);
-}
-```
-
-This is likely the function you'll use the most, but you can also:
-
-- access all the values of a utility with `utilities-get-values`, which will always return a map to simplify their processing
-- access a specific option with `utilities-get-option`
-- or even all the options with `utilities-get-options`