Create scss-docs shortcode to get some snippets from the Scss sourc…

…e files
twbs · Apr 3, 2020 · b6b6c51 · b6b6c51
1 parent e8e6d64
commit b6b6c51
Show file tree

Hide file tree

Showing 12 changed files with 64 additions and 87 deletions.
diff --git a/scss/_alert.scss b/scss/_alert.scss
@@ -40,12 +40,12 @@
 }
 
 
-// Alternate styles
-//
+// scss-docs start alert-modifiers
 // Generate contextual modifier classes for colorizing the alert.
 
 @each $color, $value in $theme-colors {
   .alert-#{$color} {
     @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
@@ -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
@@ -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
@@ -145,11 +145,13 @@
 }
 
 
-// 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.
 
 @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
@@ -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
@@ -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
@@ -1,7 +1,9 @@
+// scss-docs start clearfix
 @mixin clearfix() {
   &::after {
     display: block;
     clear: both;
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,25 @@
+{{- /*
+  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.
+*/ -}}
+
+{{- $name := .Get "name" -}}
+{{- $start := print "// scss-docs start " $name "\n" -}}
+{{- $end := print "\n// scss-docs end " $name -}}
+{{- $regex := print $start "(.|\n)*" $end -}}
+
+{{- $file := .Get "file" -}}
+
+{{- $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 "" -}}
+
+{{- highlight $result "scss" "" -}}