diff --git a/docs/docs/glamor.md b/docs/docs/glamor.md index b910a009cfa0f..d34d35f13c926 100644 --- a/docs/docs/glamor.md +++ b/docs/docs/glamor.md @@ -2,8 +2,7 @@ title: Glamor --- -Let's create a page using -[Glamor](https://github.com/threepointone/glamor). It might be useful for you to explore [CSS Modules](/tutorial/part-two/#css-modules) and [Styled Components](../styled-components/) to see how Glamor compares as a styling method. +In this guide, we'll walk through setting up a site with the CSS-in-JS library [Glamor](https://github.com/threepointone/glamor). 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. @@ -12,31 +11,32 @@ One of the most important problems they solve is selector name collisions. With 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 very easy to know how to edit a component's CSS as there's never any confusion about how and where CSS is being used. -First, install the Gatsby plugin for Glamor. +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 Gatsby plugin for Glamor. ```shell npm install --save gatsby-plugin-glamor ``` -And then add it to your `gatsby-config.js` +And then add it to your site's `gatsby-config.js`: -```javascript{9} +```javascript module.exports = { plugins: [ - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography.js`, - }, - }, `gatsby-plugin-glamor`, ], } ``` -Restart `gatsby develop` again to enable the Glamor plugin. +Then in your terminal run `gatsby develop` to start the Gatsby development server. -Now create the Glamor page at `src/pages/about-glamor.js` +Now let's create a sample Glamor page at `src/pages/index.js` ```jsx import React from "react"; @@ -51,8 +51,7 @@ export default () => ( ); ``` -Let's add the same inline `User` component that you would use for CSS Modules, but this time using Glamor's `css` -prop. +Let's add a inline `User` component using Glamor's `css` prop. ```jsx{5-27,33-40} import React from "react" @@ -100,6 +99,6 @@ export default () => ``` -If you are using Glamor in Part Two of the tutorials, the final Glamor page should look identical to the CSS Modules page. +### Final result -![glamor-example](glamor-example.png) +![glamor page](../tutorial/part-two/glamor-example.png) diff --git a/docs/docs/styled-components.md b/docs/docs/styled-components.md index de7fb52cffbf6..4016a1bccb41e 100644 --- a/docs/docs/styled-components.md +++ b/docs/docs/styled-components.md @@ -2,40 +2,39 @@ title: Styled Components --- -[Styled Components](https://www.styled-components.com/) is an example of using CSS-in-JS. It might be useful for you to explore [CSS Modules](/tutorial/part-two/) and [Glamor](../glamor/) to see how Styled Components compares as a styling method. +In this guide, we'll walk through setting up a site with the CSS-in-JS library [Styled Components](https://www.styled-components.com/). -Styled Components lets you use actual CSS syntax inside your components. Like Glamor, Styled Components is a variant on "CSS-in-JS"—which solves many of the problems with traditional CSS. +Styled Components lets you use actual CSS syntax inside your components. Styled Components 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 very easy to know how to edit a component's CSS as there's never any confusion about how and where CSS is being used. -First, we'll install the Gatsby plugin for Styled Components. +First, open a new terminal window and run the following to create a new site: + +```shell +gatsby new styled-components-tutorial https://github.com/gatsbyjs/gatsby-starter-hello-world +``` + +Second, we'll install the Gatsby plugin for Styled Components. ```sh npm install --save gatsby-plugin-styled-components styled-components ``` -Then modify the `gatsby-config.js`. If you've previously used the Glamor plugin in this site, -you'll need to remove the Glamor plugin and delete the Glamor component page we -created. The two plugins conflict with each other as both want to take control -during server rendering. +And then add it to your site's `gatsby-config.js`: -```javascript{9} +```javascript module.exports = { plugins: [ - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography.js`, - }, - }, `gatsby-plugin-styled-components`, ], } ``` -Then at `src/pages/about-styled-components.js` create: +Then in your terminal run `gatsby develop` to start the Gatsby development server. + +Now let's create a sample Styled Components page at `src/pages/index.js`: ```jsx import React from "react"; diff --git a/docs/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index 34d697d12f5af..a22b1b229a724 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -112,7 +112,9 @@ Let's start by creating a new site. At this point it probably makes sense to clo Similar to part one, open a new terminal window and run the following to create a new site: - gatsby new tutorial-part-two https://github.com/gatsbyjs/gatsby-starter-hello-world +```shell +gatsby new tutorial-part-two https://github.com/gatsbyjs/gatsby-starter-hello-world +``` This creates a new site with the following structure. diff --git a/www/src/pages/docs/doc-links.yaml b/www/src/pages/docs/doc-links.yaml index 7bc27be0fd76d..84bb552e56171 100644 --- a/www/src/pages/docs/doc-links.yaml +++ b/www/src/pages/docs/doc-links.yaml @@ -44,8 +44,6 @@ link: /docs/environment-variables/ - title: Gatsby on Windows link: /docs/gatsby-on-windows/ - - title: Using CSS-in-JS library Glamor - link: /docs/glamor/ - title: How Gatsby Works with GitHub Pages link: /docs/how-gatsby-works-with-github-pages/ - title: Migrating from v0 to v1 @@ -54,6 +52,8 @@ link: /docs/path-prefix/ - title: Proxying API Requests link: /docs/api-proxy/ + - title: Using CSS-in-JS library Glamor + link: /docs/glamor/ - title: Using CSS-in-JS library Styled Components link: /docs/styled-components/ - title: Adding Markdown Pages