Backport #32795 (#32809)

* Clarify Sass import and customize docs for how to modify variable defaults

* Add an npm starter project callout to a few pages

diff --git a/site/content/docs/4.5/getting-started/build-tools.md b/site/content/docs/4.5/getting-started/build-tools.md
index 4045f7d60e3028084d772f1bfd6425846c4f09db..12293a2361e498300fe94b0ec9224a34637a49be 100644 (file)
--- a/site/content/docs/4.5/getting-started/build-tools.md
+++ b/site/content/docs/4.5/getting-started/build-tools.md
@@ -30,6 +30,10 @@ Our [package.json]({{< param repo >}}/blob/v{{< param current_version >}}/packag
 
 Run `npm run` to see all the npm scripts.
 
+{{< callout info >}}
+{{< partial "callout-info-npm-starter.md" >}}
+{{< /callout >}}
+
 ## Autoprefixer
 
 Bootstrap uses [Autoprefixer][autoprefixer] (included in our build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3.

diff --git a/site/content/docs/4.5/getting-started/download.md b/site/content/docs/4.5/getting-started/download.md
index 3b3bc7b2cab922cec0f4e6c8d9f970e2b67d0d20..0a43f826695c9895042f98a5a4de4e68713d02cd 100644 (file)
--- a/site/content/docs/4.5/getting-started/download.md
+++ b/site/content/docs/4.5/getting-started/download.md
@@ -70,6 +70,10 @@ Bootstrap's `package.json` contains some additional metadata under the following
 - `sass` - path to Bootstrap's main [Sass](https://sass-lang.com/) source file
 - `style` - path to Bootstrap's non-minified CSS that's been precompiled using the default settings (no customization)
 
+{{< callout info >}}
+{{< partial "callout-info-npm-starter.md" >}}
+{{< /callout >}}
+
 ### yarn
 
 Install Bootstrap in your Node.js powered apps with [the yarn package](https://yarnpkg.com/en/package/bootstrap):

diff --git a/site/content/docs/4.5/getting-started/theming.md b/site/content/docs/4.5/getting-started/theming.md
index 23992f19d215b79521a4fa94adc527ebee5df2d9..1f895db82eafe0148ee8277a0df0c91a0a3cd57f 100644 (file)
--- a/site/content/docs/4.5/getting-started/theming.md
+++ b/site/content/docs/4.5/getting-started/theming.md
@@ -50,6 +50,8 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 // Option A: Include all of Bootstrap
 
 @import "../node_modules/bootstrap/scss/bootstrap";
+
+// Add custom code after this
 ```
 
 ```scss
@@ -61,6 +63,8 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 @import "../node_modules/bootstrap/scss/variables";
 @import "../node_modules/bootstrap/scss/mixins";
 
+// Include custom variable default overrides here
+
 // Optional
 @import "../node_modules/bootstrap/scss/reboot";
 @import "../node_modules/bootstrap/scss/type";
@@ -73,25 +77,39 @@ With that setup in place, you can begin to modify any of the Sass variables and
 
 ### Variable defaults
 
-Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
+Every Sass variable in Bootstrap includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
 
 You will find the complete list of Bootstrap's variables in `scss/_variables.scss`. Some variables are set to `null`, these variables don't output the property unless they are overridden in your configuration.
 
-Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap's Sass files.
+Variable overrides must come after our functions, variables, and mixins are imported, but before the rest of the imports.
 
 Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
 
 ```scss
+// Required
+@import "../node_modules/bootstrap/scss/functions";
+@import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/mixins";
+
 // Your variable overrides
 $body-bg: #000;
 $body-color: #111;
 
 // Bootstrap and its default variables
-@import "../node_modules/bootstrap/scss/bootstrap";
+
+// Optional
+@import "../node_modules/bootstrap/scss/root";
+@import "../node_modules/bootstrap/scss/reboot";
+@import "../node_modules/bootstrap/scss/type";
+// etc
 ```
 
 Repeat as necessary for any variable in Bootstrap, including the global options below.
 
+{{< callout info >}}
+{{< partial "callout-info-npm-starter.md" >}}
+{{< /callout >}}
+
 ### Maps and loops
 
 Bootstrap 4 includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. We use Sass maps for our colors, grid breakpoints, and more. Just like Sass variables, all Sass maps include the `!default` flag and can be overridden and extended.

diff --git a/site/layouts/partials/callout-info-npm-starter.md b/site/layouts/partials/callout-info-npm-starter.md
new file mode 100644 (file)
index 0000000..bbd3897
--- /dev/null
+++ b/site/layouts/partials/callout-info-npm-starter.md
@@ -0,0 +1 @@
+**Get started with Bootstrap via npm with our starter project!** Head to the [twbs/bootstrap-npm-starter](https://github.com/twbs/bootstrap-npm-starter) template repository to see how to build and customize Bootstrap in your own npm project. Includes Sass compiler, Autoprefixer, Stylelint, PurgeCSS, and Bootstrap Icons.