Docs: add Sass deprecations notices (#41283)

Co-authored-by: Mark Otto <markdotto@gmail.com>
Co-authored-by: Julien Déramond <juderamond@gmail.com>

diff --git a/.cspell.json b/.cspell.json
index 484af2af58d73f4fe1c1782753e54d92df0dbf02..b55fc872639c0273514f0bff3cfb24ff0d3ae630 100644 (file)
--- 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
index 37d134d8dd7ecd89f5a7b07f9cb1b9e2a058419f..049d6f19db7542fb2de1aef8e54f47349f786bf4 100644 (file)
--- 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
index c2c74bafd1e7c7e022b6514e19762b59f6637b6b..0adb1d3222d1d301a93ba63a88138ae3c6fe9839 100644 (file)
--- 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
index 3a27d65eb83f2b61ea52bb7b94bc4264e3c2c9f7..81e19e3bb47e816dc1b41fe44e1554c479a50cc5 100644 (file)
--- 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
index 02eb6c540e77f1fc73a4bacad6c82ae186e46ccd..74963e79e12d417bb5ad25a447a93693c70e120a 100644 (file)
--- 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