Docs: add Sass deprecations notices (#41283)

MaxLardenois · mdo · julien-deramond · web-flow · commit 6f10a1edbbd6 · 2025-04-07T20:23:25.000+02:00
Co-authored-by: Mark Otto &lt;markdotto@gmail.com&gt;
Co-authored-by: Julien Déramond &lt;juderamond@gmail.com&gt;
diff --git a/.cspell.json b/.cspell.json
@@ -87,6 +87,7 @@
     "roboto",
     "RTLCSS",
     "ruleset",
+    "sassrc",
     "screenreaders",
     "scrollbars",
     "scrollspy",
diff --git a/site/content/docs/5.3/customize/sass.md b/site/content/docs/5.3/customize/sass.md
@@ -8,6 +8,9 @@ toc: true
 
 Utilize our source Sass files to take advantage of variables, maps, mixins, and more.
 
+{{< callout warning >}}
+Sass deprecation warnings are shown when compiling source Sass files with the latest versions of Dart Sass. This does not prevent compilation or usage of Bootstrap. We're [working on a long-term fix]({{< param repo >}}/issues/40962), but in the meantime these deprecation notices can be ignored.
+{{< /callout >}}
 ## File structure
 
 Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you're using a package manager like npm, you'll have a file structure that looks like this:
diff --git a/site/content/docs/5.3/getting-started/parcel.md b/site/content/docs/5.3/getting-started/parcel.md
@@ -132,6 +132,14 @@ Importing Bootstrap into Parcel requires two imports, one into our `styles.scss`
 
    *You can also import our stylesheets individually if you want. [Read our Sass import docs]({{< docsref "/customize/sass#importing" >}}) for details.*
 
+   **Optional:** You may see Sass deprecation warnings with the latest versions of Dart Sass. These can silenced by adding the following configuration in a `.sassrc.js` file in the root folder with the following:
+
+   ```js
+   module.exports = {
+     silenceDeprecations: ['import', 'mixed-decls', 'color-functions', 'global-builtin']
+   }
+   ```
+
 2. **Import Bootstrap's JS.** Add the following to `src/js/main.js` to import all of Bootstrap's JS. Popper will be imported automatically through Bootstrap.
 
    <!-- eslint-skip -->
diff --git a/site/content/docs/5.3/getting-started/vite.md b/site/content/docs/5.3/getting-started/vite.md
@@ -94,10 +94,25 @@ With dependencies installed and our project folder ready for us to start coding,
      },
      server: {
        port: 8080
-     }
+     },
+     // Optional: Silence Sass deprecation warnings. See note below.
+     css: {
+        preprocessorOptions: {
+           scss: {
+             silenceDeprecations: [
+               'import',
+               'mixed-decls',
+               'color-functions',
+               'global-builtin',
+             ],
+           },
+        },
+     },
    }
    ```
 
+   **Note:** Sass deprecation warnings are shown when compiling source Sass files with the latest versions of Dart Sass. This does not prevent compilation or usage of Bootstrap. We're [working on a long-term fix]({{< param repo >}}/issues/40962), but in the meantime these deprecation notices can be ignored.
+
 2. **Next we fill in `src/index.html`.** This is the HTML page Vite will load in the browser to utilize the bundled CSS and JS we'll add to it in later steps.
 
    ```html
diff --git a/site/content/docs/5.3/getting-started/webpack.md b/site/content/docs/5.3/getting-started/webpack.md
@@ -203,7 +203,18 @@ Importing Bootstrap into Webpack requires the loaders we installed in the first
              },
              {
                // Loads a SASS/SCSS file and compiles it to CSS
-               loader: 'sass-loader'
+               loader: 'sass-loader',
+               options: {
+                 sassOptions: {
+                   // Optional: Silence Sass deprecation warnings. See note below.
+                   silenceDeprecations: [
+                     'mixed-decls',
+                     'color-functions',
+                     'global-builtin',
+                     'import'
+                   ]
+                 }
+               }
              }
            ]
          }
@@ -214,6 +225,8 @@ Importing Bootstrap into Webpack requires the loaders we installed in the first
 
    Here's a recap of why we need all these loaders. `style-loader` injects the CSS into a `<style>` element in the `<head>` of the HTML page, `css-loader` helps with using `@import` and `url()`, `postcss-loader` is required for Autoprefixer, and `sass-loader` allows us to use Sass.
 
+   **Note:** Sass deprecation warnings are shown when compiling source Sass files with the latest versions of Dart Sass. This does not prevent compilation or usage of Bootstrap. We're [working on a long-term fix]({{< param repo >}}/issues/40962), but in the meantime these deprecation notices can be ignored.
+
 2. **Now, let's import Bootstrap's CSS.** Add the following to `src/scss/styles.scss` to import all of Bootstrap's source Sass.
 
    ```scss
