Clearly document whether a component (or example) is dependent on other SCSS files

[celestehorgan]

Clearly document whether a component is dependent on other Bootstrap SCSS files in Bootstrap 4.x.

Some components are dependent on other SCSS Bootstrap classes for full or partial functionality. Document these clearly for each component, so that new users to Bootstrap 4.x can use this clearly.

The documentation on on importing SCSS classes is thin, and making many of the examples on the documentation website work involves troubleshooting imports.

Example use case:

When using the Navbar component in Bootstrap 4.x, the documentation on importing SCSS classes is woefully thin. Based purely on the instruction to look at bootstrap.scss's import order, one might assume based on filename alone that you would only need to import navbar in your custom SCSS file like so:

@import "bootstrap/scss/navbar";

The reality is that the Navbar class depends on a minimum of the following:

//Required
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

@import "bootstrap/scss/transitions";

In most use cases, it also requires the following:

//If using dropdowns for submenus
@import "bootstrap/scss/dropdown";

// If right-aligning anything
@import "bootstrap/scss/utilities";

To make the first example on the docs page work with a copy-and-paste, you also need the following:

// Styles the searchbox 

@import "bootstrap/scss/forms";
@import "bootstrap/scss/buttons";

[mdo]

Should we document this in the hosted docs, in the Sass files (comment at the top?), both, or something else?

[ydmitry]

In docs certainly, and what about supress @warn if I don't have specific imports ? or maybe Sass module system is capable to handle this https://github.com/twbs/bootstrap/issues/29853 ?

[mdo]

We'll get over to Dart Sass, but I'm not sure about the module system yet. That looked like it's be a bigger lift than we can take right now.

[celestehorgan]

👋

Hi, I logged this because I'm actually a technical writer with the Cloud Native Computing Foundation :)

My suggestion for you, from a documentation/writing standpoint is to document it on each component's page: For example, for Navbar, I'd include a section called "Prerequisites" or "Dependencies", directly before or after "How it works" or after.

Something like this:

---

Dependencies

If you are importing Bootstrap modularly, you must import the following for Navbar to render correctly: (or smth along these lines)

@import blah
@import blah
@import navbar

How it works

.... //etc

[mdo]

WIP of doing something small in our Sass files to get started: https://github.com/twbs/bootstrap/pull/31744.

As a bonus, as previous comments mentioned, getting this going will help us all out for that Dart Sass move if/when we migrate into the new module system.

[aakoch]

I have a similar but simpler request: list all of the files included in node_modules/bootstrap/scss/bootstrap on https://getbootstrap.com/docs/5.0/customize/sass/#importing ? I want to be able to use the functions and customize the styling. I tried just selecting the components I needed but I evidently missed some dependencies and had to go through the files in node_modules to grab more files until it worked. It would have been useful to have a list of everything.