docs(www): 25 Workflows - Adding CSS and/or Sass (#14779)

* chore: cleanup readme for sass plugin

* fix: missing guidelist components

* fix: consistency between similar docs, headings, and adding beginnings of sass guide

* docs: adding to sass guide

* Update docs/docs/sass.md

Co-Authored-By: Marcy Sutton <[email protected]>

* Update packages/gatsby-plugin-sass/README.md

Co-Authored-By: Marcy Sutton <[email protected]>

* Apply suggestions from code review

Co-Authored-By: Marcy Sutton <[email protected]>

Author: gillkyle

docs/docs/css-in-js.md

@@ -20,4 +20,4 @@ _Note that this functionality is not a part of React or Gatsby, and requires usi
 
 This section contains guides for styling your site with some of the most popular CSS-in-JS libraries, including how to set up global styles using each library.
 
-[[guidelist]]
+<GuideList slug={props.slug} />

docs/docs/css-libraries-and-frameworks.md

@@ -7,4 +7,4 @@ There are many other CSS libraries and frameworks that you can use in your Gatsb
 
 These are not full-on approaches to styling, and generally work no matter which styling approach you've chosen for your website. They require installing third-party libraries, often with the help of Gatsby community plugins.
 
-[[guidelist]]
+<GuideList slug={props.slug} />

docs/docs/post-css.md

@@ -4,11 +4,11 @@ title: PostCSS
 
 PostCSS transforms extended syntaxes and features into modern, browser-friendly CSS. This guide will show you how to get started with Gatsby and PostCSS.
 
-### Installation and Configuration
+## Installing and Configuring PostCSS
 
 This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the [**Quick Start guide**](/docs), then come back.
 
-1.  Install the Gatsby plugin [**gatsby-plugin-postcss**](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-postcss).
+1.  Install the Gatsby plugin [**gatsby-plugin-postcss**](/packages/gatsby-plugin-postcss/).
 
 `npm install --save gatsby-plugin-postcss`
 
@@ -18,13 +18,11 @@ This guide assumes that you have a Gatsby project set up. If you need to set up
 plugins: [`gatsby-plugin-postcss`],
 ```
 
-3.  Write your stylesheets using PostCSS (.css files) and require or import them as normal.
-
-If you need to pass options to PostCSS use the plugins options; see [postcss-loader](https://github.com/postcss/postcss-loader) for all available options.
+> **Note**: If you need to pass options to PostCSS use the plugins options; see [postcss-loader](https://github.com/postcss/postcss-loader) for all available options.
 
-#### Syntax example
+3.  Write your stylesheets using PostCSS (.css files) and require or import them as normal.
 
-```css
+```css:styles.css
 @custom-media --med (width <= 50rem);
 
 @media (--med) {
@@ -36,6 +34,10 @@ If you need to pass options to PostCSS use the plugins options; see [postcss-loa
 }
 ```
 
+```javascript
+import "./styles.css"
+```
+
 ### With CSS Modules
 
 Using CSS modules requires no additional configuration. Simply prepend `.module` to the extension. For example: `App.css -> App.module.css`. Any file with the module extension will use CSS modules.
@@ -69,6 +71,6 @@ module.exports = () => ({
 })
 ```
 
-### Other resources
+## Other resources
 
 - [Introduction to postcss](https://www.smashingmagazine.com/2015/12/introduction-to-postcss/)

docs/docs/sass.md

@@ -0,0 +1,57 @@
+---
+title: Using Sass in Gatsby
+---
+
+[Sass](https://sass-lang.com) is an extension of CSS, adding nested rules, variables, mixins, selector inheritance, and more. In Gatsby, Sass code can be translated to well-formatted, standard CSS using a plugin.
+
+Sass will compile `.sass` and `.scss` files to `.css` files for you, so you can write your stylesheets with more advanced features.
+
+> **Note**: the difference between using a `.sass` or `.scss` file is the syntax that you write your styles in. All valid CSS is valid SCSS as well so it is the easiest to use and most popular. You can read more about the differences in the [Sass documentation](https://sass-lang.com/documentation/syntax).
+
+## Installing and Configuring Sass
+
+This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the [**Quick Start guide**](/docs), then come back.
+
+1.  Install the Gatsby plugin [**gatsby-plugin-sass**](/packages/gatsby-plugin-sass/).
+
+`npm install --save gatsby-plugin-sass`
+
+2.  Include the plugin in your `gatsby-config.js` file.
+
+```javascript:title=gatsby-config.js
+plugins: [`gatsby-plugin-sass`],
+```
+
+> **Note**: You can configure [additional plugin options](/packages/gatsby-plugin-sass/#other-options) like paths to include and options for `css-loader`.
+
+3.  Write your stylesheets as `.sass` or `.scss` files and require or import them as normal.
+
+```css:styles.scss
+$font-stack: Helvetica, sans-serif;
+$primary-color: #333;
+
+body {
+  font: 100% $font-stack;
+  color: $primary-color;
+}
+```
+
+```css:styles.sass
+$font-stack:    Helvetica, sans-serif
+$primary-color: #333
+
+body
+  font: 100% $font-stack
+  color: $primary-color
+```
+
+```javascript
+import "./styles.scss"
+import "./styles.sass"
+```
+
+## Other resources
+
+- [Introduction to Sass](https://designmodo.com/introduction-sass/)
+- [Sass Documentation](https://sass-lang.com/documentation)
+- [Gatsby starters that use Sass](/starters/?c=Styling%3ASCSS)

docs/docs/tailwind-css.md

@@ -4,9 +4,7 @@ title: Tailwind CSS
 
 Tailwind is a utility-first CSS framework for rapidly building custom user interfaces. This guide will show you how to get started with Gatsby and [Tailwind CSS](https://tailwindcss.com/).
 
-This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the [**Quick Start guide**](/docs/quick-start), then come back.
-
-### Overview
+## Overview
 
 There are two ways you can use Tailwind with Gatsby:
 
@@ -17,6 +15,8 @@ You have to install and configure Tailwind for both of these methods, so this gu
 
 ## Installing and Configuring Tailwind
 
+This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the [**Quick Start guide**](/docs/quick-start), then come back.
+
 1. Install Tailwind
 
 ```shell
@@ -31,7 +31,7 @@ To configure Tailwind, we'll need to add a Tailwind configuration file. Luckily,
 ./node_modules/.bin/tailwind init
 ```
 
-## Option #1: PostCSS
+### Option #1: PostCSS
 
 1.  Install the Gatsby PostCSS plugin [**gatsby-plugin-postcss**](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-postcss).
 
@@ -61,7 +61,7 @@ You can now use the `@tailwind` directives to add Tailwind's utilites, preflight
 
 To learn more about how to use Tailwind in your CSS, visit the [Tailwind Documentation](https://tailwindcss.com/docs/installation#3-use-tailwind-in-your-css)
 
-## Option #2: CSS-in-JS
+### Option #2: CSS-in-JS
 
 These steps assume you have a CSS-in-JS library already installed, and the examples are based on Styled Components.
 
@@ -82,7 +82,7 @@ const Button = styled.button`
 `
 ```
 
-### Other resources
+## Other resources
 
 - [Introduction to PostCSS](https://www.smashingmagazine.com/2015/12/introduction-to-postcss/)
 - [Tailwind Documentation](https://tailwindcss.com/)

packages/gatsby-plugin-sass/README.md

@@ -9,31 +9,28 @@ Provides drop-in support for SASS/SCSS stylesheets
 ## How to use
 
 1. Include the plugin in your `gatsby-config.js` file.
-2. Write your stylesheets in SASS/SCSS and require or import them as normal.
 
-```javascript
-// in gatsby-config.js
+```javascript:title="gatsby-config.js"
 plugins: [`gatsby-plugin-sass`]
 ```
 
-By Default `node-sass` is used. To use `dart-sass`.
+2. Write your stylesheets in Sass/SCSS and require or import them as normal.
 
-```bash
-npm i -D sass
+```css:title="src/index.sass"
+html {
+  background-color: rebeccapurple;
+  p {
+    color: white;
+  }
+}
 ```
 
 ```javascript
-// in gatsby-config.js
-plugins: [
-  {
-    resolve: `gatsby-plugin-sass`,
-    options: {
-      implementation: require("sass"),
-    },
-  },
-]
+import("./src/index.sass")
 ```
 
+## Other options
+
 If you need to pass options to Sass use the plugins options, see [node-sass](https://github.com/sass/node-sass)/[dart-sass](https://github.com/sass/dart-sass) docs
 for all available options.
 
@@ -66,27 +63,27 @@ plugins: [
 ]
 ```
 
-### With CSS Modules
+### Alternative Sass Implementations
 
-Using CSS Modules requires no additional configuration. Simply prepend `.module` to the extension. For example: `App.scss` -> `App.module.scss`.
-Any file with the `module` extension will use CSS Modules.
+By default the node implementation of Sass (`node-sass`) is used. To use the implementation written in Dart (`dart-sass`), you can install `sass` instead of `node-sass` and pass it into the options as the implementation:
 
-### PostCSS plugins
-
-PostCSS is also included to handle some default optimizations like autoprefixing
-and common cross-browser flexbox bugs. Normally you don't need to think about it, but if
-you'd prefer to add additional postprocessing to your SASS output you can specify plugins
-in the plugin options
-
-## Relative paths & url()
-
-This plugin resolves `url()` paths relative to the entry SCSS/SASS file not – as might be expected – the location relative to the declaration. Under the hood, it makes use of [sass-loader](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url) and this is documented in the [readme](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url).
-
-Using [resolve-url-loader](https://github.com/bholloway/resolve-url-loader) may provide a workaround, but at present this is not in the build and implementation would demand customisation.
+```bash
+npm install --save-dev sass
+```
 
-TODO link to a plugin that adds resolve-url-loader
+```javascript
+// in gatsby-config.js
+plugins: [
+  {
+    resolve: `gatsby-plugin-sass`,
+    options: {
+      implementation: require("sass"),
+    },
+  },
+]
+```
 
-## Other options
+### SASS Precision
 
 SASS defaults to [5 digits of precision](https://github.com/sass/sass/issues/1122). If this is too low for you (e.g. [if you use Bootstrap](https://github.com/twbs/bootstrap-sass/blob/master/README.md#sass-number-precision)), you may configure it as follows:
 
@@ -103,6 +100,26 @@ plugins: [
 ]
 ```
 
+### With CSS Modules
+
+Using CSS Modules requires no additional configuration. Simply prepend `.module` to the extension. For example: `App.scss` -> `App.module.scss`.
+Any file with the `module` extension will use CSS Modules.
+
+### PostCSS plugins
+
+PostCSS is also included to handle some default optimizations like autoprefixing
+and common cross-browser flexbox bugs. Normally you don't need to think about it, but if
+you'd prefer to add additional postprocessing to your Sass output you can specify plugins
+in the plugin options.
+
+## Relative paths & url()
+
+This plugin resolves `url()` paths relative to the entry SCSS/Sass file not – as might be expected – the location relative to the declaration. Under the hood, it makes use of [sass-loader](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url) and this is documented in the [readme](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url).
+
+Using [resolve-url-loader](https://github.com/bholloway/resolve-url-loader) may provide a workaround, but at present this is not in the build and implementation would demand customization.
+
+<!-- TODO link to a plugin that adds resolve-url-loader -->
+
 ## Breaking changes history
 
 <!-- Please keep the breaking changes list ordered with the newest change at the top -->

www/src/data/sidebars/doc-links.yaml

@@ -210,6 +210,8 @@
               items:
                 - title: Typography.js
                   link: /docs/typography-js/
+                - title: Using Sass
+                  link: /docs/sass/
                 - title: Using PostCSS
                   link: /docs/post-css/
                 - title: Using TailwindCSS