Document how to disable generated classes and still use the util() mixin

diff --git a/scss/utilities/_api.scss b/scss/utilities/_api.scss
index 3b52e8235ef02a5a73924b9583fb91dd87bc9ba0..32f6adb1f0f953c2c00656a2d1c34fa96cee7b61 100644 (file)
--- a/scss/utilities/_api.scss
+++ b/scss/utilities/_api.scss
@@ -51,8 +51,6 @@
 
 $utilities-map: build-utilities-map(); // stylelint-disable-line scss/dollar-variable-default
 
-// Sometimes it’s useful for a mixin to be able to take any number of arguments. If the last argument in a @mixin declaration ends in ..., then all extra arguments to that mixin are passed to that argument as a list. This argument is known as an argument list.
-
 @mixin util($classes...) {
   @each $class in $classes {
     @if map-has-key($utilities-map, $class) {

diff --git a/site/content/docs/5.3/utilities/mixin.md b/site/content/docs/5.3/utilities/mixin.md
index 34a8fbfd4b210da5c38af5d46658dc598dc61fcf..4579643fc72582623f6e1efc38bf103af6f216ca 100644 (file)
--- a/site/content/docs/5.3/utilities/mixin.md
+++ b/site/content/docs/5.3/utilities/mixin.md
@@ -113,7 +113,7 @@ Include multiple utilities in a single `util()` mixin call with a comma separate
 }
 ```
 
-## Custom setup
+## Usage
 
 Want to use only the utilities and mixin in your own project? In your project's Sass file, include the following:
 
@@ -136,3 +136,32 @@ Want to use only the utilities and mixin in your own project? In your project's
   color: purple;
 }
 ```
+
+### Disable generated utilities
+
+The `util()` mixin is powered by Sass placeholders, not the generated classes in the compiled CSS. This means you can disable the generated classes and still use the mixin in your custom Sass.
+
+To do this, disable the `$enable-utility-classes` global option, import the required Sass files, and start using the new mixin.
+
+```scss
+// Disable the generated utility classes
+$enable-utility-classes: false;
+
+// Required Bootstrap imports
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/variables-dark";
+@import "bootstrap/scss/maps";
+@import "bootstrap/scss/mixins";
+@import "bootstrap/scss/root";
+
+// Import the utilities maps and mixins
+@import "bootstrap/scss/utilities";
+@import "bootstrap/scss/utilities/api";
+
+// Write your own styles
+.test {
+  @include util(d-inline-flex, p-4, mb-md-3);
+  color: purple;
+}
+```
\ No newline at end of file