Skip to content

docs: add Sass deprecations notice in docs #41283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 7, 2025
Merged

docs: add Sass deprecations notice in docs #41283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
59f813b
docs: add Sass deprecations notices in docs
MaxLardenois Mar 7, 2025
4170739
docs: add Parcel config for Sass deprecation silencing, correct Sass …
MaxLardenois Mar 10, 2025
98ff8c2
Apply suggestions from code review
mdo Apr 6, 2025
eac60eb
Merge branch 'main' into sass-deprecation-doc
julien-deramond Apr 7, 2025
d14fee7
Add 'sassrc' to cspell list
julien-deramond Apr 7, 2025
a7fdd9a
Move explanation after having actually included the Sass files
julien-deramond Apr 7, 2025
077d0e8
Consistency with comments
julien-deramond Apr 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@
"roboto",
"RTLCSS",
"ruleset",
"sassrc",
"screenreaders",
"scrollbars",
"scrollspy",
Expand Down
3 changes: 3 additions & 0 deletions site/content/docs/5.3/customize/sass.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions site/content/docs/5.3/getting-started/parcel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down
17 changes: 16 additions & 1 deletion site/content/docs/5.3/getting-started/vite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 14 additions & 1 deletion site/content/docs/5.3/getting-started/webpack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
]
}
}
}
]
}
Expand All @@ -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
Expand Down