From af89cf32c0368c2dae3bcbc89154c1d699851e1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20M=C3=A9tral?= Date: Mon, 20 May 2019 21:19:14 +0200 Subject: [PATCH] [docs] Restructure styling section (#13766) * Add comment to create draft PR * Add comment to create draft PR * Draft styling section structure * Draft styling section intro * Remove guide from Glamor, poin to Emotion Keep the file to avoid any broken links, but discourage using it * Write CSS-in-JS section intro * Write Cascading and Scoped styles intro * Write Frameworks and Libraries intro * Write stubs * Remove Component CSS page This was essentially a duplicate of CSS Modules, with an intro to component-scoped CSS. Keeping the page to avoid broken links, redirecting to Scoped Styles * Structure in three sub-sections 1. Global CSS Files 2. Mudular CSS 3. Stylized Components (4. other frameworks and libraries) * Write Global CSS intro * Copy content from Global Styles to Global CSS approach * Copy content from Global Styles to Emotion guide * Rewrite Styling section intro * Add page at creating-global-styles to avoid broken links * Add links in styling approaches description * Write CSS-in-JS motivations draft * Rewrite approaches titles * Apply language and details suggestions from review Co-Authored-By: robinmetral * Rename page to fit section order CSS Frameworks and Libraries -> CSS Libraries and Frameworks * Add note about stable classes for user stylesheets * Add section on importing CSS files into components * Update CSS-in-JS from suggestion Mention there are global style sections in each CSS-in-JS guide Co-Authored-By: Marcy Sutton * Rewrite CSS Modules page with component CSS intro * title tweaks and content updates * Redirect Component CSS to CSS Modules * Apply suggestions from code review Co-Authored-By: gillkyle * Improve links out to guides on Global Styles page * chore: format * fix heading levels --- docs/docs/component-css.md | 48 ------- docs/docs/creating-global-styles.md | 168 +--------------------- docs/docs/css-in-js.md | 23 +++ docs/docs/css-libraries-and-frameworks.md | 10 ++ docs/docs/css-modules.md | 71 ++++++--- docs/docs/emotion.md | 56 ++++++++ docs/docs/glamor.md | 105 +------------- docs/docs/global-css.md | 145 +++++++++++++++++++ docs/docs/layout-components.md | 2 +- docs/docs/styled-components.md | 22 +++ docs/docs/styling.md | 8 +- www/gatsby-node.js | 6 + www/src/data/sidebars/doc-links.yaml | 36 ++--- 13 files changed, 347 insertions(+), 353 deletions(-) delete mode 100644 docs/docs/component-css.md create mode 100644 docs/docs/css-in-js.md create mode 100644 docs/docs/css-libraries-and-frameworks.md create mode 100644 docs/docs/global-css.md diff --git a/docs/docs/component-css.md b/docs/docs/component-css.md deleted file mode 100644 index 227d68aa427b1..0000000000000 --- a/docs/docs/component-css.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Component CSS ---- - -### Component CSS - -Gatsby has a wealth of options available for styling components. This example will explore one very popular and useful method: CSS Modules - [homepage](https://github.com/css-modules/css-modules). If you would like to see a more in-depth tutorial, please refer to [the Component CSS tutorial](/tutorial/part-two/#component-css). - -### CSS Module Example - -CSS Modules enable the use of writing normal CSS safely. Gone are the worries of selector name collisions. - -There are two important parts in utilizing CSS Modules. Since it works out of the box with Gatsby, all you need are: - -- A React component -- A `module.css` file - -For the sake of an example, a `module.css` file called `container.module.css` will be created under a new directory called `src/components` with the following contents. - -```css:title=src/components/container.module.css -.container { - margin: 3rem auto; - max-width: 600px; -} -``` - -Now, a React component called `Container` (`container.js`) will be created in the same directory `src/components` with the following contents. Make note that the `module.css` file created earlier is imported. - -```javascript:title=src/components/container.js -import React from "react" -import containerStyles from "./container.module.css" - -export default ({ children }) => ( -
{children}
-) -``` - -Also make sure to notice that the `.container` style that you created is referred to as `containerStyles.container` because of the name of the import. - -Following the same logic, you have the ability of creating multiple `module.css` files for multiple React components. - -You may take a look at a more in-depth [Component CSS tutorial](/tutorial/part-two/#component-css) if you would like to see an example with explanation of multiple complex React components utilizing multiple `module.css` files and why you may want to use CSS Modules in your next project. - -### CSS Modules and BEM - -If you're used to writing CSS with the [BEM](http://getbem.com/) methodology, a quick thing to note is that CSS Modules camelizes class names that contain dashes. - -For example: `block--modifier` turns into `blockModifier`. diff --git a/docs/docs/creating-global-styles.md b/docs/docs/creating-global-styles.md index 74a49ce2366c5..672d46dab921f 100644 --- a/docs/docs/creating-global-styles.md +++ b/docs/docs/creating-global-styles.md @@ -2,168 +2,8 @@ title: Creating global styles --- -In nearly every site, there will be some global styles, such as a reset or typography defaults. This guide will walk through how to add global styles to your site, whether you use standard `.css` files (or with preprocessors like Sass/Less) or a CSS-in-JS solution. +Creating global styles for your Gatsby site depends on your styling approach, so we've moved the instructions to the relevant guides: -## Table of Contents - -- [How to add global styles in Gatsby with standard CSS files](#how-to-add-global-styles-in-gatsby-with-standard-css-files) -- [How to add global styles in Gatsby using CSS-in-JS](#how-to-add-global-styles-in-gatsby-using-css-in-js) -- [Add global styles with CSS files and no layout component](#add-global-styles-with-css-files-and-no-layout-component) - -## How to add global styles in Gatsby with standard CSS files - -The best way to add global styles is with a [shared layout component](/tutorial/part-three/#your-first-layout-component). This layout component is used for things that are shared throughout the site, including styles, header components, and other common items. - -> **NOTE:** This pattern is implemented by default in [the default starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/02324e5b04ea0a66d91c7fe7408b46d0a7eac868/src/layouts/index.js#L6). - -To create a shared layout with global styles, start by creating a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world). - -```shell -gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world -``` - -Open your new site in your code editor and create a new directory at `/src/components`. Inside, create two new files: - -```diff - global-styles/ - └───src/ - └───components/ -+ │ │─ layout.js -+ │ └─ layout.css - │ - └───pages/ - └─ index.js -``` - -Inside `src/components/layout.css`, add some global styles: - -```css:title=src/components/layout.css -div { - background: red; - color: white; -} -``` - -In `src/components/layout.js`, include the stylesheet and export a layout component: - -```jsx:title=src/components/layout.js -import React from "react" -import "./layout.css" - -export default ({ children }) =>
{children}
-``` - -Finally, update `src/pages/index.js` to use the new layout component: - -```jsx:title=src/pages/index.js -import React from "react" -import Layout from "../components/layout" - -export default () => Hello world! -``` - -Run `npm run develop` and you’ll see the global styles applied. - -![Global styles](./images/global-styles.png) - -## How to add global styles in Gatsby using CSS-in-JS - -> **NOTE:** For this example, we’ll be using [Emotion](https://emotion.sh), but the implementation is similar for other CSS-in-JS solutions as well. - -To start, create a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world) and install [`gatsby-plugin-emotion`](/packages/gatsby-plugin-emotion/) and its dependencies: - -```shell -gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world -cd global-styles -npm install --save gatsby-plugin-emotion @emotion/core @emotion/styled -``` - -Create `gatsby-config.js` and add the Emotion plugin: - -```js:title=gatsby-config.js -module.exports = { - plugins: [`gatsby-plugin-emotion`], -} -``` - -Next, add a layout component at `src/components/layout.js`: - -```jsx:title=src/components/layout.js -import React from "react" -import { Global, css } from "@emotion/core" -import styled from "@emotion/styled" - -const Wrapper = styled("div")` - border: 2px solid green; - padding: 10px; -` - -export default ({ children }) => ( - - - {children} - -) -``` - -Then, update `src/pages/index.js` to use the layout: - -```jsx:title=src/pages/index.js -import React from "react" -import Layout from "../components/layout" - -export default () => Hello world! -``` - -Run `npm run build`, and you can see in `public/index.html` that the styles have been inlined globally. - -## Add global styles with CSS files and no layout component - -In some cases, using a shared layout component is not desirable. In these cases, you can include a global stylesheet using `gatsby-browser.js`. - -> **NOTE:** This approach does _not_ work with CSS-in-JS. Use shared components to share styles in CSS-in-JS. - -First, open a new terminal window and run the following commands to create a new default Gatsby site and start the development server: - -```shell -gatsby new global-style-tutorial https://github.com/gatsbyjs/gatsby-starter-default -cd global-style-tutorial -npm run develop -``` - -Second, create a css file and define any styles you wish. An arbitrary example: - -```css:title=src/styles/global.css -html { - background-color: peachpuff; -} - -a { - color: rebeccapurple; -} -``` - -Then, include the stylesheet in your site's `gatsby-browser.js` file. - -> **NOTE:** This solution works when including css as those styles are extracted when building the JavaScript but not for css-in-js. -> Including styles in a layout component or a global-styles.js is your best bet for that. - -```javascript:title=gatsby-browser.js -import "./src/styles/global.css" - -// or: -// require('./src/styles/global.css') -``` - -> _Note: You can use Node.js require or import syntax. Additionally, the placement of the example css file in a `src/styles` folder is arbitrary._ - -You should see your global styles taking effect across your site: - -![Global styles example site](./images/global-styles-example.png) +- [Global styles with standard CSS files](/docs/global-css/) (also applies if you're using CSS Modules for component-scoped styles) +- [Global styles with CSS-in-JS library Emotion](/docs/emotion/) +- [Global styles with CSS-in-JS library Styled-Components](/docs/styled-components/) diff --git a/docs/docs/css-in-js.md b/docs/docs/css-in-js.md new file mode 100644 index 0000000000000..141db04ef078e --- /dev/null +++ b/docs/docs/css-in-js.md @@ -0,0 +1,23 @@ +--- +title: Enhancing Styles with CSS-in-JS +overview: true +--- + +CSS-in-JS refers to an approach where styles are written in JavaScript instead of in external CSS files to easily scope styles in components, eliminate dead code, encourage faster performance and dynamic styling, and more. + +CSS-in-JS bridges the gap between CSS and JavaScript: + +1. **Components**: you'll style your site with components, which integrates well with React's "everything is a component" philosophy. +2. **Scoped**: this is a side effect of the first. Just like [CSS Modules](/docs/css-modules/), CSS-in-JS is scoped to components by default. +3. **Dynamic**: style your site dynamically based on component state by integrating JavaScript variables. +4. **Bonuses**: many CSS-in-JS libraries generate unique class names which can help with caching, automatic vendor prefixes, timely loading of critical CSS, and implementing many other features, depending on the library you choose. + +CSS-in-JS, while not required in Gatsby, is very popular among JavaScript developers for the reasons listed above. For more context, read Max Stoiber's (creator of CSS-in-JS library [styled-components](/docs/styled-components/)) article [_Why I write CSS in JavaScript_](https://mxstbr.com/thoughts/css-in-js/). However, you should also consider whether CSS-in-JS is necessary, as not relying on it can encourage more inclusive front-end skill-sets. It is also more difficult to port styles from JSX to and from CSS. + +_Note that this functionality is not a part of React or Gatsby, and requires using any of the many [third-party CSS-in-JS libraries](https://github.com/MicheleBertoli/css-in-js#css-in-js)._ + +> Adding a stable CSS class to your JSX markup along with your CSS-in-JS can make it easier to users to include [User Stylesheets](https://www.viget.com/articles/inline-styles-user-style-sheets-and-accessibility/) for accessibility. See [Styled Components](/docs/styled-components#enabling-user-stylesheets-with-a-stable-class-name) example. + +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]] diff --git a/docs/docs/css-libraries-and-frameworks.md b/docs/docs/css-libraries-and-frameworks.md new file mode 100644 index 0000000000000..78800e1446b6d --- /dev/null +++ b/docs/docs/css-libraries-and-frameworks.md @@ -0,0 +1,10 @@ +--- +title: CSS Libraries and Frameworks +overview: true +--- + +There are many other CSS libraries and frameworks that you can use in your Gatsby project. + +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]] diff --git a/docs/docs/css-modules.md b/docs/docs/css-modules.md index 60c2a00ad8717..da5874c6b8d13 100644 --- a/docs/docs/css-modules.md +++ b/docs/docs/css-modules.md @@ -1,28 +1,67 @@ --- -title: CSS Modules +title: Component-Scoped Styles with CSS Modules --- -## CSS modules and Gatsby +Component-scoped CSS allows you to write traditional, portable CSS with minimal side-effects: gone are the worries of selector name collisions or affecting other components' styles. -Gatsby works out of the box with CSS Modules. Here is an [example site that uses CSS modules](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-css-modules). +Gatsby works out of the box with [CSS Modules](https://github.com/css-modules/css-modules), a popular solution for writing component-scoped CSS. Here is an [example site that uses CSS Modules](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-css-modules). -## What is a CSS module? +## What is a CSS Module? -Quoting from -[the CSS Module homepage](https://github.com/css-modules/css-modules): +Quoting from [the CSS Module homepage](https://github.com/css-modules/css-modules): -> A **CSS Module** is a CSS file in which all class names and animation names -> are scoped locally by default. +> A **CSS Module** is a CSS file in which all class names and animation names are scoped locally by default. -CSS Modules are very popular as they let you write CSS like normal but with a lot -more safety. The tool automatically makes class and animation names unique so -you don't have to worry about selector name collisions. +CSS Modules let you write styles in CSS files but consume them as JavaScript objects for additional processing and safety. CSS Modules are very popular because they automatically make class and animation names unique so you don't have to worry about selector name collisions. -## When to use CSS modules +### CSS Module example -CSS Modules are highly recommended for those new to building with Gatsby (and -React in general). +The CSS in a CSS module is no different than normal CSS, but the extension of the file is different to mark that the file will be processed. -## How to build a page using CSS modules +```css:title=src/components/container.module.css +.container { + margin: 3rem auto; + max-width: 600px; +} +``` -Visit the [CSS Modules section of the tutorial](/tutorial/part-two/#css-modules) to learn how to build a page using CSS modules. +```jsx:title=src/components/container.js +import React from "react" +// highlight-next-line +import containerStyles from "./container.module.css" + +export default ({ children }) => ( + // highlight-next-line +
{children}
+) +``` + +In this example, a CSS module is imported and declared as a JavaScript object called `containerStyles`. Then, a CSS class from that object is referenced in the JSX `className` attribute with `containerStyles.container`, which renders into HTML with dynamic CSS class names like `container-module--container--3MbgH`. + +### Enabling user stylesheets with a stable class name + +Adding a persistent CSS `className` to your JSX markup along with your CSS Modules code can make it easier for users to take advantage of [User Stylesheets](https://www.viget.com/articles/inline-styles-user-style-sheets-and-accessibility/) for accessibility. + +Here's an example where the class name `container` is added to the DOM along with the module's dynamically-created class names: + +```jsx:title=src/components/container.js +import React from "react" +import containerStyles from "./container.module.css" + +export default ({ children }) => ( +
+ {children} +
+) +``` + +A site user could then write their own CSS styles matching HTML elements with a class name of `.container`, and it wouldn't be affected if the CSS module name or path changed. + +## When to use CSS Modules + +CSS Modules are highly recommended for those new to building with Gatsby (and React in general) as they allow you to write regular, portable CSS files while gaining +performance benefits like only bundling referenced code. + +## How to build a page using CSS Modules + +Visit the [CSS Modules section of the tutorial](/tutorial/part-two/#css-modules) for a guided tour of building a page with CSS Modules. diff --git a/docs/docs/emotion.md b/docs/docs/emotion.md index e64d6887bc575..1965c9afe2732 100644 --- a/docs/docs/emotion.md +++ b/docs/docs/emotion.md @@ -113,3 +113,59 @@ export default () => ( ) ``` + +## Adding global styles in Gatsby with Emotion + +To start, create a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world) and install [`gatsby-plugin-emotion`](/packages/gatsby-plugin-emotion/) and its dependencies: + +```shell +gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world +cd global-styles +npm install --save gatsby-plugin-emotion @emotion/core @emotion/styled +``` + +Create `gatsby-config.js` and add the Emotion plugin: + +```js:title=gatsby-config.js +module.exports = { + plugins: [`gatsby-plugin-emotion`], +} +``` + +Next, add a layout component at `src/components/layout.js`: + +```jsx:title=src/components/layout.js +import React from "react" +import { Global, css } from "@emotion/core" +import styled from "@emotion/styled" + +const Wrapper = styled("div")` + border: 2px solid green; + padding: 10px; +` + +export default ({ children }) => ( + + + {children} + +) +``` + +Then, update `src/pages/index.js` to use the layout: + +```jsx:title=src/pages/index.js +import React from "react" +import Layout from "../components/layout" + +export default () => Hello world! +``` + +Run `npm run build`, and you can see in `public/index.html` that the styles have been inlined globally. diff --git a/docs/docs/glamor.md b/docs/docs/glamor.md index b844fd3fcc8b0..4673ca6ae1823 100644 --- a/docs/docs/glamor.md +++ b/docs/docs/glamor.md @@ -2,107 +2,4 @@ title: Glamor --- -In this guide, you will learn setting up a site with the CSS-in-JS library [Glamor](https://github.com/threepointone/glamor). - -Glamor is not actively maintained, the maintainer recommends using [Emotion](/docs/emotion). - -Glamor lets you write _real_ CSS inline in your components using the same Object -CSS syntax React supports for the `style` prop. Glamor is a variant on "CSS-in-JS"—which solves many of the problems with traditional CSS. - -One of the most important problems they solve is selector name collisions. With traditional CSS, you have to be careful not to overwrite CSS selectors used elsewhere in a site because all CSS selectors live in the same global namespace. This unfortunate restriction can lead to elaborate (and often confusing) selector naming schemes. - -With CSS-in-JS, you avoid all that as CSS selectors are scoped automatically to their component. Styles are tightly coupled with their components. This makes it easier to know how to edit a component's CSS as there's never any confusion about how and where CSS is being used. - -First, open a new terminal window and run the following to create a new site: - -```shell -gatsby new glamor-tutorial https://github.com/gatsbyjs/gatsby-starter-hello-world -``` - -Second, install the necessary dependencies for Glamor and Gatsby. - -```shell -npm install --save gatsby-plugin-glamor glamor -``` - -And then add it to your site's `gatsby-config.js`: - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [`gatsby-plugin-glamor`], -} -``` - -Then in your terminal run `npm run develop` to start the Gatsby development server. - -Now let's create a sample Glamor page at `src/pages/index.js` - -```jsx:title=src/pages/index.js -import React from "react" - -const Container = ({ children }) =>
{children}
- -export default () => ( - -

About Glamor

-

Glamor is cool

- -) -``` - -Let's add css styles to `Container` and add an inline `User` component using Glamor's `css` prop. - -```jsx:title=src/pages/index.js -import React from "react" - -const Container = ({ children }) => ( -
{children}
{/* highlight-line */} -) - -// highlight-start -const User = props => ( -
- -
-

{props.username}

-

{props.excerpt}

-
-
-) - -export default () => ( - - {/* highlight-end */} -

About Glamor

-

Glamor is cool

- {/* highlight-line */} - - {/* highlight-start */} - - - {/* highlight-end */} -) -``` - -### Final result - -![glamor page](../tutorial/part-two/glamor-example.png) +CSS-in-JS library [Glamor](https://github.com/threepointone/glamor) is not actively maintained. the maintainer recommends using [Emotion](/docs/emotion/). diff --git a/docs/docs/global-css.md b/docs/docs/global-css.md new file mode 100644 index 0000000000000..17d50bd5c2927 --- /dev/null +++ b/docs/docs/global-css.md @@ -0,0 +1,145 @@ +--- +title: Standard Styling with Global CSS Files +--- + +Traditionally, websites are styled using global CSS files. + +Globally-scoped CSS rules are declared in external `.css` stylesheets, and [CSS specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) and [the Cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade) determine how styles are applied. + +## Adding global styles with a layout component + +The best way to add global styles is with a [shared layout component](/tutorial/part-three/#your-first-layout-component). This layout component is used for things that are shared throughout the site, including styles, header components, and other common items. + +> **NOTE:** This pattern is implemented by default in [the default starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/02324e5b04ea0a66d91c7fe7408b46d0a7eac868/src/layouts/index.js#L6). + +To create a shared layout with global styles, start by creating a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world). + +```shell +gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world +``` + +Open your new site in your code editor and create a new directory at `/src/components`. Inside, create two new files: + +```diff + global-styles/ + └───src/ + └───components/ ++ │ │─ layout.js ++ │ └─ layout.css + │ + └───pages/ + └─ index.js +``` + +Inside `src/components/layout.css`, add some global styles: + +```css:title=src/components/layout.css +div { + background: red; + color: white; +} +``` + +In `src/components/layout.js`, include the stylesheet and export a layout component: + +```jsx:title=src/components/layout.js +import React from "react" +import "./layout.css" + +export default ({ children }) =>
{children}
+``` + +Finally, update `src/pages/index.js` to use the new layout component: + +```jsx:title=src/pages/index.js +import React from "react" +import Layout from "../components/layout" + +export default () => Hello world! +``` + +Run `npm run develop` and you’ll see the global styles applied. + +![Global styles](./images/global-styles.png) + +## Adding global styles without a layout component + +In some cases, using a shared layout component is not desirable. In these cases, you can include a global stylesheet using `gatsby-browser.js`. + +> **NOTE:** This approach does _not_ work with CSS-in-JS. Use shared components to share styles in CSS-in-JS. + +First, open a new terminal window and run the following commands to create a new default Gatsby site and start the development server: + +```shell +gatsby new global-style-tutorial https://github.com/gatsbyjs/gatsby-starter-default +cd global-style-tutorial +npm run develop +``` + +Second, create a CSS file and define any styles you wish. An example: + +```css:title=src/styles/global.css +html { + background-color: peachpuff; +} + +a { + color: rebeccapurple; +} +``` + +Then, include the stylesheet in your site's `gatsby-browser.js` file. + +> **NOTE:** This solution works when including css as those styles are extracted when building the JavaScript but not for css-in-js. +> Including styles in a layout component or a global-styles.js is your best bet for that. + +```javascript:title=gatsby-browser.js +import "./src/styles/global.css" + +// or: +// require('./src/styles/global.css') +``` + +> _Note: You can use Node.js require or import syntax. Additionally, the placement of the example css file in a `src/styles` folder is arbitrary._ + +You should see your global styles taking effect across your site: + +![Global styles example site](./images/global-styles-example.png) + +### Importing CSS files into components + +It is also possible to break up your CSS styles into separate files so that team members can work independently while still using traditional CSS. You can then [import files directly](/docs/importing-assets-into-files/) into pages, templates, or components: + +```css:title=menu.css +.menu { + background-color: black; + color: #fff; + display: flex; +} +``` + +```javascript:title=components/menu.js +import "css/menu.css" +``` + +This approach can simplify integration of CSS or [Sass](/packages/gatsby-plugin-sass/) styles into your Gatsby site by allowing team members to write and consume more traditional, class-based CSS. However, there are [trade-offs](#limitations) that must be considered with regards to web performance and the lack of dead code elimination. + +### Adding classes to components + +Since `class` is a reserved word in JavaScript, you'll have to use the `className` prop instead, which will render as the browser-supported `class` attribute in your HTML output. + +```jsx + +``` + +```css +.primary { + background: orangered; +} +``` + +### Limitations + +The biggest problem with global CSS files is the risk of name conflicts and side effects like unintended inheritance. + +CSS methodologies like BEM can help solve this, but a more modern solution is to write locally-scoped CSS using [CSS Modules](/docs/css-modules/) or [CSS-in-JS](/docs/css-in-js/). diff --git a/docs/docs/layout-components.md b/docs/docs/layout-components.md index 8c0ad90020229..9c8aab6c4d57a 100644 --- a/docs/docs/layout-components.md +++ b/docs/docs/layout-components.md @@ -1,5 +1,5 @@ --- -title: Layout components +title: Layout Components --- In this guide, you'll learn Gatsby's approach to layouts, how to create and use layout components, and how to prevent layout components from unmounting. diff --git a/docs/docs/styled-components.md b/docs/docs/styled-components.md index f1f83f9a9227e..d01bc10bd7f8e 100644 --- a/docs/docs/styled-components.md +++ b/docs/docs/styled-components.md @@ -109,3 +109,25 @@ export default () => ( ) ``` + +### Enabling user stylesheets with a stable class name + +Adding a persistent CSS `className` to your styled components can make it easier for users to take advantage of [User Stylesheets](https://www.viget.com/articles/inline-styles-user-style-sheets-and-accessibility/) for accessibility. + +Here's an example where the class name `container` is added to the DOM along with the Styled Components' dynamically-created class names: + +```jsx:title=src/components/container.js +import React from "react" +import styled from "styled-components" + +const Section = styled.section` + margin: 3rem auto; + max-width: 600px; +` + +export default ({ children }) => ( +
{children}
+) +``` + +A site user could then write their own CSS styles matching HTML elements with a class name of `.container`, and it wouldn't be affected if the CSS-in-JS output changed. diff --git a/docs/docs/styling.md b/docs/docs/styling.md index 0e58048097314..6f44ef0be7ef8 100644 --- a/docs/docs/styling.md +++ b/docs/docs/styling.md @@ -3,10 +3,12 @@ title: Styling overview: true --- -There are so many ways to add styles to your website -- and Gatsby supports almost every possible option, through official and community plugins. (_If there isn’t a plugin yet for your favorite option, consider [contributing one](/docs/creating-plugins/)!_) +There are many ways to style your website. They can roughly be grouped into three styling approaches: -In this section you'll find guides on different styling methods supported by Gatsby plugins. +- [**Global CSS Files**](/docs/global-css/): the traditional way to style a website. CSS rules are declared globally and styles are applied depending on specificity and inheritance. +- [**Modular Stylesheets**](/docs/css-modules): CSS rules are written traditionally but consumed with JavaScript and scoped locally to avoid unintended side-effects elsewhere. Works out-of-the-box with Gatsby. +- [**CSS-in-JS**](/docs/css-in-js/): locally-scoped CSS written and consumed in JavaScript, enabling the easier use of dynamic styling and other features. Requires the use of third-party libraries. -Gatsby doesn't prescribe or dictate any single styling approach. Choose what works best for you! +Gatsby doesn't have an opinion about which styling approach you choose. Almost every possible option is supported through official and community plugins. _(If there isn’t a plugin yet for your favorite option, consider [contributing](/docs/creating-plugins) one!)_ [[guidelist]] diff --git a/www/gatsby-node.js b/www/gatsby-node.js index 5457240d55123..96855fb68542e 100644 --- a/www/gatsby-node.js +++ b/www/gatsby-node.js @@ -46,6 +46,12 @@ const slugToAnchor = slug => exports.createPages = ({ graphql, actions, reporter }) => { const { createPage, createRedirect } = actions + createRedirect({ + fromPath: `/docs/component-css/`, // Merged Component CSS and CSS Modules + toPath: `/docs/css-modules/`, + isPermanent: true, + }) + createRedirect({ fromPath: `/blog/2018-10-25-unstructured-data/`, toPath: `/blog/2018-10-25-using-gatsby-without-graphql/`, diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 54651f024b2f2..e01a8f0d62b72 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -192,24 +192,26 @@ items: - title: Using Layout Components link: /docs/layout-components/ - - title: Using CSS Modules + - title: Standard, Global CSS Files + link: /docs/global-css/ + - title: Component-Scoped CSS Modules link: /docs/css-modules/ - - title: Using Typography.js - link: /docs/typography-js/ - - title: Using CSS-in-JS Library Emotion - link: /docs/emotion/ - - title: Using CSS-in-JS Library Glamor - link: /docs/glamor/ - - title: Using CSS-in-JS Library Styled Components - link: /docs/styled-components/ - - title: Creating Global Styles - link: /docs/creating-global-styles/ - - title: Writing Component CSS - link: /docs/component-css/ - - title: Using PostCSS - link: /docs/post-css/ - - title: Using TailwindCSS - link: /docs/tailwind-css/ + - title: Enhancing with CSS-in-JS + link: /docs/css-in-js/ + items: + - title: Emotion + link: /docs/emotion/ + - title: Styled-Components + link: /docs/styled-components/ + - title: CSS Libraries and Frameworks + link: /docs/css-libraries-and-frameworks/ + items: + - title: Typography.js + link: /docs/typography-js/ + - title: Using PostCSS + link: /docs/post-css/ + - title: Using TailwindCSS + link: /docs/tailwind-css/ - title: Adding Components to Content with MDX link: /docs/mdx/ items: