Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): reformat tutorials part 1-8 #22205

Closed
wants to merge 1 commit into from
Closed

chore(docs): reformat tutorials part 1-8 #22205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/tutorial/part-eight/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ npm install --save gatsby-plugin-manifest
```javascript:title=gatsby-config.js
{
plugins: [
// highlight-start
{
resolve: `gatsby-plugin-manifest`,
options: {
Expand All @@ -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
]
}
```
Expand Down Expand Up @@ -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/).

Expand Down
8 changes: 5 additions & 3 deletions docs/tutorial/part-five/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?

Expand All @@ -14,15 +14,15 @@ 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`.

<video controls="controls" autoplay="true" loop="true">
<source type="video/mp4" src="/graphiql-explore.mp4" />
<p>Your browser does not support the video element.</p>
</video>

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 <kbd>Ctrl + Space</kbd> (or use <kbd>Shift + Space</kbd> as an alternate keyboard shortcut) to bring up the autocomplete window and <kbd>Ctrl + Enter</kbd> 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 <kbd>Ctrl + Space</kbd> (or use <kbd>Shift + Space</kbd> as an alternate keyboard shortcut) to bring up the autocomplete window and <kbd>Ctrl + Enter</kbd> to run the GraphQL query. You'll be using GraphiQL a lot more through the remainder of the tutorial.

## Using the GraphiQL Explorer

Expand Down Expand Up @@ -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
Expand Down
90 changes: 55 additions & 35 deletions docs/tutorial/part-four/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -18,16 +18,15 @@ 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

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.
Expand All @@ -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

Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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)
Expand All @@ -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 `<h1 />` 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 `<h1 />` 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.

Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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)

Expand Down
28 changes: 16 additions & 12 deletions docs/tutorial/part-one/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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`.
snitin315 marked this conversation as resolved.
Show resolved Hide resolved

### ✋ Using sub-components

Expand Down Expand Up @@ -244,7 +246,7 @@ Over in `header.js`, the header component expects to receive the `headerText` pr
<h1>{props.headerText}</h1>
```

> 💡 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 `<Header />` component, like so...

Expand Down Expand Up @@ -285,7 +287,7 @@ You'll often want to link between pages — Let's look at routing in a Gatsby si

### ✋ Using the `<Link />` component

1. Open the index page component (`src/pages/index.js`), import the `<Link />` component from Gatsby, add a `<Link />` 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 `<Link />` component from Gatsby, add a `<Link />` 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"
Expand Down Expand Up @@ -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.

<video controls="controls" loop="true">
<source type="video/mp4" src="./10-linking-between-pages.mp4" />
Expand All @@ -348,7 +350,9 @@ npm install --global surge
surge login
```

Next, build your site by running the following command in the terminal at the root of your site (tip: make sure you're running this command at the root of your site, in this case in the hello-world folder, which you can do by opening a new tab in the same window you used to run `gatsby develop`):
Next, build your site by running the following command in the terminal at the root of your site.

> 💡 Make sure you're running this command at the root of your site, in this case in the `hello-world` folder, which you can do by opening a new tab in the same window you used to run `gatsby develop`.

```shell
gatsby build
Expand All @@ -368,7 +372,7 @@ Then finally deploy your site by publishing the generated files to surge.sh.
surge public/
```

> Note that you will have to press the `enter` key after you see the `domain: some-name.surge.sh` information on your command-line interface.
> 💡 Note that you will have to press the `enter` key after you see the `domain: some-name.surge.sh` information on your command-line interface.

Once this finishes running, you should see in your terminal something like:

Expand Down
8 changes: 6 additions & 2 deletions docs/tutorial/part-seven/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/), [part 5](/tutorial/part-five/), and [part 6](/tutorial/part-six/) 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/), [part 5](/tutorial/part-five/), and [part 6](/tutorial/part-six/) before continuing here.

## What's in this tutorial?

Expand All @@ -30,7 +30,7 @@ It is also referred to as the ‘path’ but this tutorial will use the term ‘

Creating new pages has two steps:

1. Generate the "path" or "slug" for the page.
1. Generate the ‘path‘ or ‘slug‘ for the page.
2. Create the page.

_**Note**: Often data sources will directly provide a slug or pathname for content — when working with one of those systems (e.g. a CMS), you don't need to create the slugs yourself as you do with markdown files._
Expand Down Expand Up @@ -90,6 +90,8 @@ exports.onCreateNode = ({ node, getNode }) => {
}
```

> 💡 To avoid replication Gatsby stores at `node.parent` only a reference to the file node as an id like `70e062ec-ffb0-575c-98e8-281943630b27`. In an GraphQL query this references are solved for you by the query runner. But in `onCreateNode` you need the helper function `getNode` which takes this id to get the node.

After restarting your development server, you should see the relative paths for your two markdown
files print to the terminal screen.

Expand Down Expand Up @@ -448,3 +450,5 @@ Now that you've built a Gatsby site, where do you go next?
- Explore more [plugins](/docs/plugins/)
- See what [other people are building with Gatsby](/showcase/)
- Check out the documentation on [Gatsby's APIs](/docs/api-specification/), [nodes](/docs/node-interface/), or [GraphQL](/docs/graphql-reference/)

Continue on to [part eight of the tutorial](/tutorial/part-eight/) where you'll preparing your site to go live!
Loading