Update Sass docs to mention compiling and including (#38538)

Co-authored-by: Julien Déramond <[email protected]>
twbs · Jun 1, 2023 · 6bb6015 · 6bb6015
1 parent 0d9715e
commit 6bb6015
Showing 1 changed file with 47 additions and 6 deletions.
diff --git a/site/content/docs/5.3/customize/sass.md b/site/content/docs/5.3/customize/sass.md
@@ -17,9 +17,10 @@ your-project/
 ├── scss
 │   └── custom.scss
 └── node_modules/
-    └── bootstrap
-        ├── js
-        └── scss
+│   └── bootstrap
+│       ├── js
+│       └── scss
+└── index.html
 ```
 
 If you've downloaded our source files and aren't using a package manager, you'll want to manually create something similar to that structure, keeping Bootstrap's source files separate from your own.
@@ -28,9 +29,10 @@ If you've downloaded our source files and aren't using a package manager, you'll
 your-project/
 ├── scss
 │   └── custom.scss
-└── bootstrap/
-    ├── js
-    └── scss
+├── bootstrap/
+│   ├── js
+│   └── scss
+└── index.html
 ```
 
 ## Importing
@@ -85,6 +87,45 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 
 With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.
 
+## Compiling
+
+In order to use your custom Sass code as CSS in the browser, you need a Sass compiler. Sass ships as a CLI package, but you can also compile it with other build tools like [Gulp](https://gulpjs.com/) or [Webpack](https://webpack.js.org/), or with a GUI applications. Some IDEs also have Sass compilers built in or as downloadable extensions.
+
+We like to use the CLI to compile our Sass, but you can use whichever method you prefer. From the command line, run the following:
+
+```shell
+# Install Sass globally
+npm install -g sass
+
+# Watch your custom Sass for changes and compile it to CSS
+sass --watch ./scss/custom.scss ./css/custom.css
+```
+
+Learn more about your options at [sass-lang.com/install](https://sass-lang.com/install) and [compiling with VS Code](https://code.visualstudio.com/docs/languages/css#_transpiling-sass-and-less-into-css).
+
+{{< callout info >}}
+**Using Bootstrap with another build tool?** Consider reading our guides for compiling with [WebPack]({{< docsref "/getting-started/webpack" >}}), [Parcel]({{< docsref "/getting-started/parcel" >}}), or [Vite]({{< docsref "/getting-started/vite" >}}). We also have production-ready demos in [our examples repository on GitHub](https://github.com/twbs/examples).
+{{< /callout >}}
+
+## Including
+
+Once your CSS is compiled, you can include it in your HTML files. Inside your `index.html` you'll want to include your compiled CSS file. Be sure to update the path to your compiled CSS file if you've changed it.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Custom Bootstrap</title>
+    <link href="/css/custom.css" rel="stylesheet">
+  </head>
+  <body>
+    <h1>Hello, world!</h1>
+  </body>
+</html>
+```
+
 ## Variable defaults
 
 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.