diff --git a/docs/tutorial/part-eight/index.md b/docs/tutorial/part-eight/index.md index 49d500149a579..c8a6153163646 100644 --- a/docs/tutorial/part-eight/index.md +++ b/docs/tutorial/part-eight/index.md @@ -93,6 +93,7 @@ npm install --save gatsby-plugin-manifest ```javascript:title=gatsby-config.js { plugins: [ + // highlight-start { resolve: `gatsby-plugin-manifest`, options: { @@ -107,6 +108,7 @@ npm install --save gatsby-plugin-manifest icon: `src/images/icon.png`, // This path is relative to the root of the site. }, }, + // highlight-end ] } ``` @@ -365,7 +367,7 @@ Well, not quite; just for this tutorial. There are [Additional Tutorials](/tutor This is just the beginning. Keep going! -- Did you build something cool? Share it on Twitter, tag [#buildwithgatsby](https://twitter.com/search?q=%23buildwithgatsby), and [@mention us](https://twitter.com/gatsbyjs)! +- Did you build something cool? Share it on Twitter, tag [#buildwithgatsby](https://twitter.com/search?q=%23buildwithgatsby), and mention us with [@gatsbyjs](https://twitter.com/gatsbyjs)! - Did you write a cool blog post about what you learned? Share that, too! - Contribute! Take a stroll through [open issues](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) on the gatsby repo and [become a contributor](/contributing/how-to-contribute/). diff --git a/docs/tutorial/part-five/index.md b/docs/tutorial/part-five/index.md index b09690e34f0e4..a933e4806cbc3 100644 --- a/docs/tutorial/part-five/index.md +++ b/docs/tutorial/part-five/index.md @@ -4,7 +4,7 @@ typora-copy-images-to: ./ disableTableOfContents: true --- -> This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through [part 4](/tutorial/part-four/) before continuing here. +> 💡 This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through [part 4](/tutorial/part-four/) before continuing here. ## What's in this tutorial? @@ -14,7 +14,7 @@ In this tutorial, you'll be learning about how to pull data into your Gatsby sit GraphiQL is the GraphQL integrated development environment (IDE). It's a powerful (and all-around awesome) tool you'll use often while building Gatsby websites. -You can access it when your site's development server is running—normally at +You can access it when your site's development server is running -- normally at `http://localhost:8000/___graphql`. -Poke around the built-in `Site` "type" and see what fields are available on it -- including the `siteMetadata` object you queried earlier. Try opening GraphiQL and play with your data! Press Ctrl + Space (or use Shift + Space as an alternate keyboard shortcut) to bring up the autocomplete window and Ctrl + Enter to run the GraphQL query. You'll be using GraphiQL a lot more through the remainder of the tutorial. +Poke around the built-in `Site` "type" and see what fields are available on it -- including the `siteMetadata` object you queried in [tutorial part 4](/tutorial/part-four/). Try opening GraphiQL and play with your data! Press Ctrl + Space (or use Shift + Space as an alternate keyboard shortcut) to bring up the autocomplete window and Ctrl + Enter to run the GraphQL query. You'll be using GraphiQL a lot more through the remainder of the tutorial. ## Using the GraphiQL Explorer @@ -101,6 +101,8 @@ each time to re-run the query. You'll see the updated query results: The result is an array of `File` "nodes" (node is a fancy name for an object in a "graph"). Each `File` node object has the fields you queried for. +> 💡 On the same level as the node `edges` is a node with the name `nodes`, which is shortcut for `edges.node`. + ## Build a page with a GraphQL query Building new pages with Gatsby often starts in GraphiQL. You first sketch out diff --git a/docs/tutorial/part-four/index.md b/docs/tutorial/part-four/index.md index 7ce1575c450eb..ad3ba0b112eb9 100644 --- a/docs/tutorial/part-four/index.md +++ b/docs/tutorial/part-four/index.md @@ -9,7 +9,7 @@ to feel pretty comfortable 😀 ## Recap of the first half of the tutorial -So far, you've been learning how to use React.js—how powerful it is to be able to +So far, you've been learning how to use React.js -- how powerful it is to be able to create your _own_ components to act as custom building blocks for websites. You’ve also explored styling components using CSS Modules. @@ -18,8 +18,7 @@ You’ve also explored styling components using CSS Modules. In the next four parts of the tutorial (including this one), you'll be diving into the Gatsby data layer, which is a powerful feature of Gatsby that lets you easily build sites from Markdown, WordPress, headless CMSs, and other data sources of all flavors. -**NOTE:** Gatsby’s data layer is powered by GraphQL. For an in-depth tutorial on -GraphQL, we recommend [How to GraphQL](https://www.howtographql.com/). +_**NOTE:** Gatsby’s data layer is powered by GraphQL. For an in-depth tutorial on GraphQL, we recommend [How to GraphQL](https://www.howtographql.com/)._ ## Data in Gatsby @@ -27,7 +26,7 @@ A website has four parts: HTML, CSS, JS, and data. The first half of the tutorial focused on the first three. Now let’s learn how to use data in Gatsby sites. -**What is data?** +### What is data? A very computer science-y answer would be: data is things like `"strings"`, integers (`42`), objects (`{ pizza: true }`), etc. @@ -49,7 +48,7 @@ Data can also live in file types like Markdown, CSV, etc. as well as databases and APIs of all sorts. **Gatsby's data layer lets you pull data from these (and any other source) -directly into your components**—in the shape and form you want. +directly into your components** -- in the shape and form you want. ## Using Unstructured Data vs GraphQL @@ -102,6 +101,32 @@ npm install --save gatsby-plugin-typography typography react-typography typograp Set up a site similar to what you ended with in [Part Three](/tutorial/part-three). This site will have a layout component and two page components: +> 💡 `gatsby-config.js` must be in the root of your project, not under `src`. + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + `gatsby-plugin-emotion`, + { + resolve: `gatsby-plugin-typography`, + options: { + pathToConfigModule: `src/utils/typography`, + }, + }, + ], +} +``` + +```javascript:title=src/utils/typography.js +import Typography from "typography" +import kirkhamTheme from "typography-theme-kirkham" + +const typography = new Typography(kirkhamTheme) + +export default typography +export const rhythm = typography.rhythm +``` + ```jsx:title=src/components/layout.js import React from "react" import { css } from "@emotion/core" @@ -174,32 +199,6 @@ export default () => ( ) ``` -```javascript:title=src/utils/typography.js -import Typography from "typography" -import kirkhamTheme from "typography-theme-kirkham" - -const typography = new Typography(kirkhamTheme) - -export default typography -export const rhythm = typography.rhythm -``` - -`gatsby-config.js` (must be in the root of your project, not under src) - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [ - `gatsby-plugin-emotion`, - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography`, - }, - }, - ], -} -``` - Add the above files and then run `gatsby develop`, per usual, and you should see the following: ![start](start.png) @@ -210,7 +209,7 @@ Now you can start querying 😋 ## Your first GraphQL query -When building sites, you'll probably want to reuse common bits of data -- like the _site title_ for example. Look at the `/about/` page. You'll notice that you have the site title (`Pandas Eating Lots`) in both the layout component (the site header) as well as in the `

` of the `about.js` page (the page header). +When building sites, you'll probably want to reuse common bits of data -- like the _site title_ for example. Look at the `/about/` page. You'll notice that you have the site title `Pandas Eating Lots` in both the layout component (the site header) as well as in the `

` of the `about.js` page (the page header). But what if you want to change the site title in the future? You'd have to search for the title across all your components and edit each instance. This is both cumbersome and error-prone, especially for larger, more complex sites. Instead, you can store the title in one location and reference that location from other files; change the title in a single place, and Gatsby will _pull_ your updated title into files that reference it. @@ -277,7 +276,7 @@ It worked! 🎉 The basic GraphQL query that retrieves the `title` in your `about.js` changes above is: ```graphql:title=src/pages/about.js -{ +query { site { siteMetadata { title @@ -293,7 +292,7 @@ Page queries live outside of the component definition -- by convention at the en ### Use a StaticQuery [StaticQuery](/docs/static-query/) is a new API introduced in Gatsby v2 that allows non-page components (like your `layout.js` component), to retrieve data via GraphQL queries. -Let's use its newly introduced hook version — [`useStaticQuery`](/docs/use-static-query/). +Let's use its newly introduced hook version -- [`useStaticQuery`](/docs/use-static-query/). Go ahead and make some changes to your `src/components/layout.js` file to use the `useStaticQuery` hook and a `{data.site.siteMetadata.title}` reference that uses this data. When you are done, your file will look like this: @@ -368,7 +367,28 @@ But let's restore the real title. One of the core principles of Gatsby is that _creators need an immediate connection to what they're creating_ ([hat tip to Bret Victor](http://blog.ezyang.com/2012/02/transcript-of-inventing-on-principle/)). In other words, when you make any change to code you should immediately see the effect of that change. You manipulate an input of Gatsby and you see the new output showing up on the screen. -So almost everywhere, changes you make will immediately take effect. Edit the `gatsby-config.js` file again, this time changing the `title` back to "Pandas Eating Lots". The change should show up very quickly in your site pages. +So almost everywhere, changes you make will immediately take effect. Edit the `gatsby-config.js` file again, this time changing the `title` back to `"Pandas Eating Lots"`: + +```javascript:title=gatsby-config.js +module.exports = { + siteMetadata: { + // highlight-start + title: "Pandas Eating Lots", + // highlight-end + }, + plugins: [ + `gatsby-plugin-emotion`, + { + resolve: `gatsby-plugin-typography`, + options: { + pathToConfigModule: `src/utils/typography`, + }, + }, + ], +} +``` + +The change should show up very quickly in your site pages. ![Both titles say Pandas Eating Lots](pandas-eating-lots-titles.png) diff --git a/docs/tutorial/part-one/index.md b/docs/tutorial/part-one/index.md index 96a065bdeb6f9..1db5e86f925f5 100644 --- a/docs/tutorial/part-one/index.md +++ b/docs/tutorial/part-one/index.md @@ -4,11 +4,11 @@ typora-copy-images-to: ./ disableTableOfContents: true --- -In the [**previous section**](/tutorial/part-zero/), you prepared your local development environment by installing the necessary software and creating your first Gatsby site using the [**“hello world” starter**](https://github.com/gatsbyjs/gatsby-starter-hello-world). Now, take a deeper dive into the code generated by that starter. +In the [**previous section**](/tutorial/part-zero/), you prepared your local development environment by installing the necessary software and creating your first Gatsby site using the [**“Hello World” starter**](https://github.com/gatsbyjs/gatsby-starter-hello-world). Now, take a deeper dive into the code generated by that starter. ## Using Gatsby starters -In [**tutorial part zero**](/tutorial/part-zero/), you created a new site based on the “hello world” starter using the following command: +In [**tutorial part zero**](/tutorial/part-zero/), you created a new site based on the “Hello World” starter using the following command: ```shell gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world @@ -24,15 +24,15 @@ If you omit a URL from the end, Gatsby will automatically generate a site for yo ### ✋ Open up the code -In your code editor, open up the code generated for your “Hello World” site and take a look at the different directories and files contained in the ‘hello-world’ directory. It should look something like this: +In your code editor, open up the code generated for your “Hello World” site and take a look at the different directories and files contained in the `hello-world` directory. It should look something like this: ![Hello World project in VS Code](01-hello-world-vscode.png) -_Note: Again, the editor shown here is Visual Studio Code. If you’re using a different editor, it will look a little different._ +_**Note:** Again, the editor shown here is Visual Studio Code. If you’re using a different editor, it will look a little different._ Let’s take a look at the code that powers the homepage. -> 💡 If you stopped your development server after running `gatsby develop` in the previous section, start it up again now — time to make some changes to the hello-world site! +> 💡 If you stopped your development server after running `gatsby develop` in the previous section, start it up again now — time to make some changes to the "Hello World" site! ## Familiarizing with Gatsby pages @@ -99,7 +99,9 @@ export default () => ( ### Wait… HTML in our JavaScript? -_If you’re familiar with React and JSX, feel free to skip this section._ If you haven’t worked with the React framework before, you may be wondering what HTML is doing in a JavaScript function. Or why we’re importing `react` on the first line but seemingly not using it anywhere. This hybrid “HTML-in-JS” is actually a syntax extension of JavaScript, for React, called JSX. You can follow along with this tutorial without prior experience with React, but if you’re curious, here’s a brief primer… +> 💡 If you’re familiar with React and JSX, feel free to skip this section. + +If you haven’t worked with the React framework before, you may be wondering what HTML is doing in a JavaScript function. Or why we’re importing `react` on the first line but seemingly not using it anywhere. This hybrid “HTML-in-JS” is actually a syntax extension of JavaScript, for React, called JSX. You can follow along with this tutorial without prior experience with React, but if you’re curious, here’s a brief primer… Consider the original contents of the `src/pages/index.js` file: @@ -169,7 +171,7 @@ export default () => ( ![New about page](05-about-page.png) -Just by putting a React component in the `src/pages/about.js` file, you now have a page accessible at `/about`. +Just by putting a React component in the `src/pages/about.js` file, you now have a page accessible at `http://localhost:8000/about`. ### ✋ Using sub-components @@ -244,7 +246,7 @@ Over in `header.js`, the header component expects to receive the `headerText` pr

{props.headerText}

``` -> 💡 In JSX, you can embed any JavaScript expression by wrapping it with `{}`. This is how you can access the `headerText` property (or “prop!”) from the “props” object. +> 💡 In JSX, you can embed any JavaScript expression by wrapping it with `{}`. This is how you can access the `headerText` property (or “prop”!) from the `props` object. If you had passed another prop to your `
` component, like so... @@ -285,7 +287,7 @@ You'll often want to link between pages — Let's look at routing in a Gatsby si ### ✋ Using the `` component -1. Open the index page component (`src/pages/index.js`), import the `` component from Gatsby, add a `` component above the header, and give it a `to` property with the value of `"/contact/"` for the pathname: +1. Open the index page component `src/pages/index.js`, import the `` component from Gatsby, add a `` component above the header, and give it a `to` property with the value of `"/contact/"` for the pathname: ```jsx:title=src/pages/index.js import React from "react" @@ -324,7 +326,7 @@ export default () => ( ) ``` -After you save the file, you should see the contact page and be able to follow the link to the homepage. +After you save the file, you need to reload the page and you should see the contact page and be able to follow the link to the homepage.