Create `scss-docs` shortcode to get some snippets from the Scs… (#30502)

Co-authored-by: XhmikosR <xhmikosr@gmail.com>

diff --git a/scss/_alert.scss b/scss/_alert.scss
index 45d621806581a5903b107965fe8eafcb8c2f9026..19157b2981a827f52aa9f88ac15ebecfeb4870ac 100644 (file)
--- a/scss/_alert.scss
+++ b/scss/_alert.scss
@@ -40,8 +40,7 @@
 }
 
 
-// Alternate styles
-//
+// scss-docs-start alert-modifiers
 // Generate contextual modifier classes for colorizing the alert.
 
 @each $color, $value in $theme-colors {
@@ -49,3 +48,4 @@
     @include alert-variant(color-level($value, $alert-bg-level), color-level($value, $alert-border-level), color-level($value, $alert-color-level));
   }
 }
+// scss-docs-end alert-modifiers

diff --git a/scss/_dropdown.scss b/scss/_dropdown.scss
index 3290f22cbb358c1a49161a2032d78f43446fd960..b30f2ba7ece61580fa053c9c4f09de4ec1d724e5 100644 (file)
--- a/scss/_dropdown.scss
+++ b/scss/_dropdown.scss
@@ -34,6 +34,7 @@
   @include box-shadow($dropdown-box-shadow);
 }
 
+// scss-docs-start responsive-breakpoints
 @each $breakpoint in map-keys($grid-breakpoints) {
   @include media-breakpoint-up($breakpoint) {
     $infix: breakpoint-infix($breakpoint, $grid-breakpoints);
@@ -49,6 +50,7 @@
     }
   }
 }
+// scss-docs-end responsive-breakpoints
 
 // Allow for dropdowns to go bottom up (aka, dropup-menu)
 // Just add .dropup after the standard .dropdown class and you're set.

diff --git a/scss/_functions.scss b/scss/_functions.scss
index 00179049c1a61260f4ce139108167bc37f1224b3..49a4604660be6a98ee3f3e6f50add14729dccdfe 100644 (file)
--- a/scss/_functions.scss
+++ b/scss/_functions.scss
@@ -128,12 +128,14 @@ $_luminance-list: .0008 .001 .0011 .0013 .0015 .0017 .002 .0022 .0025 .0027 .003
 }
 
 // Request a color level
+// scss-docs-start color-level
 @function color-level($color: $primary, $level: 0) {
   $color-base: if($level > 0, $black, $white);
   $level: abs($level);
 
   @return mix($color-base, $color, $level * $theme-color-interval);
 }
+// scss-docs-end color-level
 
 @function tint-color($color, $level) {
   @return mix(white, $color, $level * $theme-color-interval);

diff --git a/scss/_list-group.scss b/scss/_list-group.scss
index 8513cdd9d168204a99e842ca2eb005c7a03ad9c9..7378a14b814daaddfed7aea04584356279157642 100644 (file)
--- a/scss/_list-group.scss
+++ b/scss/_list-group.scss
@@ -145,7 +145,8 @@
 }
 
 
-// Contextual variants
+// scss-docs-start list-group-modifiers
+// List group contextual variants
 //
 // Add modifier classes to change text and background color on individual items.
 // Organizationally, this must come after the `:hover` states.
@@ -153,3 +154,4 @@
 @each $color, $value in $theme-colors {
   @include list-group-item-variant($color, color-level($value, $list-group-item-bg-level), color-level($value, $list-group-item-color-level));
 }
+// scss-docs-end list-group-modifiers

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 66f7357b0f04ae85814f59b81924cf0c546d95be..6f9abfa38727b85f8a5e52cb2c2a8e956e49d462 100644 (file)
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -341,6 +341,7 @@ $transition-base:             all .2s ease-in-out !default;
 $transition-fade:             opacity .15s linear !default;
 $transition-collapse:         height .35s ease !default;
 
+// scss-docs-start embed-responsive-aspect-ratios
 $embed-responsive-aspect-ratios: (
   "21by9": (
     x: 21,
@@ -359,6 +360,7 @@ $embed-responsive-aspect-ratios: (
     y: 1
   )
 ) !default;
+// scss-docs-end embed-responsive-aspect-ratios
 
 // Typography
 //
@@ -774,6 +776,7 @@ $form-feedback-icon-valid:          url("data:image/svg+xml,<svg xmlns='http://w
 $form-feedback-icon-invalid-color:  $form-feedback-invalid-color !default;
 $form-feedback-icon-invalid:        url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' fill='none' stroke='#{$form-feedback-icon-invalid-color}' viewBox='0 0 12 12'><circle cx='6' cy='6' r='4.5'/><path stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/><circle cx='6' cy='8.2' r='.6' fill='#{$form-feedback-icon-invalid-color}' stroke='none'/></svg>") !default;
 
+// scss-docs-start form-validation-states
 $form-validation-states: (
   "valid": (
     "color": $form-feedback-valid-color,
@@ -784,6 +787,7 @@ $form-validation-states: (
     "icon": $form-feedback-icon-invalid
   )
 ) !default;
+// scss-docs-end form-validation-states
 
 // Z-index master list
 //

diff --git a/scss/forms/_validation.scss b/scss/forms/_validation.scss
index d15e20899ee86251766157be407dd2d62701d7f2..acd68f2ed648d4c41769b6e9d477785aa88d3cf5 100644 (file)
--- a/scss/forms/_validation.scss
+++ b/scss/forms/_validation.scss
@@ -5,6 +5,8 @@
 // pseudo-classes but also includes `.is-invalid` and `.is-valid` classes for
 // server-side validation.
 
+// scss-docs-start form-validation-states-loop
 @each $state, $data in $form-validation-states {
   @include form-validation-state($state, map-get($data, color), map-get($data, icon));
 }
+// scss-docs-end form-validation-states-loop

diff --git a/scss/mixins/_clearfix.scss b/scss/mixins/_clearfix.scss
index 11a977b7373dab15046354e1b27b88f29acdf44f..ffc62bb285df049f1957dfa4088592b07728c7a0 100644 (file)
--- a/scss/mixins/_clearfix.scss
+++ b/scss/mixins/_clearfix.scss
@@ -1,3 +1,4 @@
+// scss-docs-start clearfix
 @mixin clearfix() {
   &::after {
     display: block;
@@ -5,3 +6,4 @@
     content: "";
   }
 }
+// scss-docs-end clearfix

diff --git a/site/content/docs/4.3/forms/validation.md b/site/content/docs/4.3/forms/validation.md
index 2d6e2cab105eb9bfa8b013d34174ecfe92153228..4613a6d7433474d7862ff1a7dbaad1da2e678ef0 100644 (file)
--- a/site/content/docs/4.3/forms/validation.md
+++ b/site/content/docs/4.3/forms/validation.md
@@ -370,24 +370,10 @@ Validation states can be customized via Sass with the `$form-validation-states`
 
 Please note that we do not recommend customizing these values without also modifying the `form-validation-state` mixin.
 
-{{< highlight scss >}}
-// Sass map from `_variables.scss`
-// Override this and recompile your Sass to generate different states
-$form-validation-states: (
-  "valid": (
-    "color": $form-feedback-valid-color,
-    "icon": $form-feedback-icon-valid
-  ),
-  "invalid": (
-    "color": $form-feedback-invalid-color,
-    "icon": $form-feedback-icon-invalid
-  )
-);
-
-// Loop from `_forms.scss`
-// Any modifications to the above Sass map will be reflected in your compiled
-// CSS via this loop.
-@each $state, $data in $form-validation-states {
-  @include form-validation-state($state, map-get($data, color), map-get($data, icon));
-}
-{{< /highlight >}}
+This is the Sass map from `_variables.scss`. Override this and recompile your Sass to generate different states:
+
+{{< scss-docs name="form-validation-states" file="scss/_variables.scss" >}}
+
+This is the loop from `forms/_validation.scss.scss`. Any modifications to the above Sass map will be reflected in your compiled CSS via this loop:
+
+{{< scss-docs name="form-validation-states-loop" file="scss/forms/_validation.scss" >}}

diff --git a/site/content/docs/4.3/getting-started/theming.md b/site/content/docs/4.3/getting-started/theming.md
index e6ed6c1982f85fd611215cbe3d6a93c27829dc39..7e5b984b8a5ea07c3e035be78b10ecfdc7b9bbee 100644 (file)
--- a/site/content/docs/4.3/getting-started/theming.md
+++ b/site/content/docs/4.3/getting-started/theming.md
@@ -172,14 +172,7 @@ In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functi
 
 We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
 
-{{< highlight scss >}}
-@function color-level($color: $primary, $level: 0) {
-  $color-base: if($level > 0, #000, #fff);
-  $level: abs($level);
-
-  @return mix($color-base, $color, $level * $theme-color-interval);
-}
-{{< /highlight >}}
+{{< scss-docs name="color-level" file="scss/_functions.scss" >}}
 
 In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
 
@@ -389,37 +382,17 @@ Many of Bootstrap's components and utilities are built with `@each` loops that i
 
 Many of Bootstrap's components are built with a base-modifier class approach. This means the bulk of the styling is contained to a base class (e.g., `.btn`) while style variations are confined to modifier classes (e.g., `.btn-danger`). These modifier classes are built from the `$theme-colors` map to make customizing the number and name of our modifier classes.
 
-Here are two examples of how we loop over the `$theme-colors` map to generate modifiers to the `.alert` component and all our `.bg-*` background utilities.
+Here are two examples of how we loop over the `$theme-colors` map to generate modifiers to the `.alert` and `.list-group` components.
 
-{{< highlight scss >}}
-// Generate alert modifier classes
-@each $color, $value in $theme-colors {
-  .alert-#{$color} {
-    @include alert-variant(color-level($color, -10), color-level($color, -9), color-level($color, 6));
-  }
-}
+{{< scss-docs name="alert-modifiers" file="scss/_alert.scss" >}}
 
-// Generate `.bg-*` color utilities
-@each $color, $value in $theme-colors {
-  @include bg-variant('.bg-#{$color}', $value);
-}
-{{< /highlight >}}
+{{< scss-docs name="list-group-modifiers" file="scss/_list-group.scss" >}}
 
 ### Responsive
 
-These Sass loops aren't limited to color maps, either. You can also generate responsive variations of your components or utilities. Take for example our responsive text alignment utilities where we mix an `@each` loop for the `$grid-breakpoints` Sass map with a media query include.
-
-{{< highlight scss >}}
-@each $breakpoint in map-keys($grid-breakpoints) {
-  @include media-breakpoint-up($breakpoint) {
-    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);
+These Sass loops aren't limited to color maps, either. You can also generate responsive variations of your components. Take for example our responsive alignment of the dropdowns where we mix an `@each` loop for the `$grid-breakpoints` Sass map with a media query include.
 
-    .text#{$infix}-left   { text-align: left !important; }
-    .text#{$infix}-right  { text-align: right !important; }
-    .text#{$infix}-center { text-align: center !important; }
-  }
-}
-{{< /highlight >}}
+{{< scss-docs name="responsive-breakpoints" file="scss/_dropdown.scss" >}}
 
 Should you need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
 

diff --git a/site/content/docs/4.3/helpers/clearfix.md b/site/content/docs/4.3/helpers/clearfix.md
index bbae9a359718617a52e690a9fb5bdbf728303e29..362fdc2b8f22ae8be77186975c1cb1f2faca4fcc 100644 (file)
--- a/site/content/docs/4.3/helpers/clearfix.md
+++ b/site/content/docs/4.3/helpers/clearfix.md
@@ -8,21 +8,19 @@ aliases: "/docs/4.3/helpers/"
 
 Easily clear `float`s by adding `.clearfix` **to the parent element**. Can also be used as a mixin.
 
+Use in HTML:
+
 {{< highlight html >}}
 <div class="clearfix">...</div>
 {{< /highlight >}}
 
-{{< highlight scss >}}
-// Mixin itself
-@mixin clearfix() {
-  &::after {
-    display: block;
-    content: "";
-    clear: both;
-  }
-}
+The mixin source code:
 
-// Usage as a mixin
+{{< scss-docs name="clearfix" file="scss/mixins/_clearfix.scss" >}}
+
+Use the mixin in SCSS:
+
+{{< highlight scss >}}
 .element {
   @include clearfix;
 }

diff --git a/site/content/docs/4.3/helpers/embed.md b/site/content/docs/4.3/helpers/embed.md
index dcc7ddad6a6c277b4444f96d9ef851227adb8766..30914b2d6442cef22f80cdf2db3ec5550753fc34 100644 (file)
--- a/site/content/docs/4.3/helpers/embed.md
+++ b/site/content/docs/4.3/helpers/embed.md
@@ -50,23 +50,4 @@ Aspect ratios can be customized with modifier classes. By default the following
 
 Within `_variables.scss`, you can change the aspect ratios you want to use. Here's an example of the `$embed-responsive-aspect-ratios` map:
 
-{{< highlight scss >}}
-$embed-responsive-aspect-ratios: (
-  "21by9": (
-    x: 21,
-    y: 9
-  ),
-  "16by9": (
-    x: 16,
-    y: 9
-  ),
-  "4by3": (
-    x: 4,
-    y: 3
-  ),
-  "1by1": (
-    x: 1,
-    y: 1
-  )
-);
-{{< /highlight >}}
+{{< scss-docs name="embed-responsive-aspect-ratios" file="scss/_variables.scss" >}}

diff --git a/site/layouts/shortcodes/scss-docs.html b/site/layouts/shortcodes/scss-docs.html
new file mode 100644 (file)
index 0000000..4a525e4
--- /dev/null
+++ b/site/layouts/shortcodes/scss-docs.html
@@ -0,0 +1,33 @@
+{{- /*
+  Usage: `scss-docs name="name" file="file/_location.scss"`
+
+    Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
+    comments in the docs.
+
+    Optional parameters:
+    strip-default: Remove the ` !default` flag from variable assignments - default: `true`
+*/ -}}
+
+{{- $name := .Get "name" -}}
+{{- $file := .Get "file" -}}
+{{- $strip_default := .Get "strip-default" | default "true" -}}
+
+{{- $start := printf "// scss-docs-start %s\n" $name -}}
+{{- $end := printf "\n// scss-docs-end %s" $name -}}
+{{- $regex := printf "%s(.|\n)*%s" $start $end -}}
+
+{{- $css := readFile $file -}}
+{{- $match := findRE $regex $css 1 -}}
+
+{{- if (eq (len $match) 0) -}}
+  {{- errorf "Got no matches for %q in %q! (called in %q)" $name $file $.Page.Path -}}
+{{- end -}}
+
+{{- $remove_start := replace (index $match 0) $start "" -}}
+{{- $result := replace $remove_start $end "" -}}
+
+{{- if (ne $strip_default "false") -}}
+  {{- $result = replace $result " !default" "" -}}
+{{- end -}}
+
+{{- highlight $result "scss" "" -}}