docs: gatsby-plugin-sass global import methods

[gillkyle]

Summary

There has been confusion with configuring Sass in sites using gatsby-plugin-sass because some methods seem to be undocumented.

This came up in a Tweet thread:
https://twitter.com/triscodes/status/1237117936281825281

(Copying the text in case the tweet is deleted):

It took me forever to figure out how to do it. Found out from some obscure gitub thread. This method is nowhere in the docs! Plus these are all utils, when I tried to use actual code (globals, typography, etc), the order was wrong. So I took them out. Are there better ways?

Some recommended topics to cover:

• Provide examples of what could be passed into the plugin's options (as part of node-sass or dart-sass) to be more explicit in the README: https://www.gatsbyjs.org/packages/gatsby-plugin-sass/#other-options - instead of just saying to refer to the other docs
• Explain global imports with more clarity in the guide on using sass with Gatsby, step 3 doesn't have a title on the code block to show that those imports should happen in the gatsby-browser file. That could be outlined like the tweet author's method shows in his tweet as well.

Motivation

Why should we document this and who will benefit from it?

Users of gatsby-plugin-sass, this is also a workflow from #13708.

Steps to resolve this issue

Covering more use cases will make these guides more practical for folks using Sass.

Draft the doc

• Make some improvements to the README to state options that can be passed in which are used by the plugin.
• Add some clarity to the example in the Using Sass guide, especially in the 3rd step.

Open a pull request

• Open a pull request with your work including the words "closes docs: gatsby-plugin-sass global import methods #22119" in the pull request description

[tr1s]

Yeah, I'm a huge proponent of thorough documentation and not assuming everyone knows everything, because I sure don't.

I was involved in the setup and development of my works education website and it was our first time using Gatsby V2 and using CSS modules. We wanted to use SCSS variables and obviously didn't want to import them into every single component manually. Like I mentioned it took me forever to find a method that allowed me to inject them in using that method I took a screenshot of. A tradeoff was that when you inject them in the from the gatsby-config.js, you don't get any VSCode helpers when you begin to start typing the variable name in the editor.. but it was worth it to have all functions, mixins, and variables accessible in all the *.module.scss files.

I assumed it would be a good idea to inject my normalize, typography, and global styles in the gatsby config as well because they are rarely changing.. but I was having issues with the ordering of the styles. Normalize was overriding global, and it appeared that no matter what order you put the files, it was just doing it's own thing.

---

Just yesterday playing around with Nuxt, I then found this out while setting up my SCSS:

Nuxt style resources posted this warning, and if it's the same situation as in Gatsby? then it would be great to know in the docs as well.

Also linking to node/sass docs which don't have any straightforward examples themselves doesn't seem like the best idea.

In this line includePaths: ["absolute/path/a", "absolute/path/b"],, it would be better to have an actual example instead. I don't know what this means, there's no simple explanation and it feels akin to seeing foo, bar, baz everywhere.

Anyways, these were just some of my experiences, hope this helps, cheers!

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[github-actions]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.
Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community! 💪💜