- ` and nested `
- ` elements.
+ * You can also use the `id` field as your unique `key` prop for each post. (React uses the `key` prop to keep track of what elements need to be re-rendered. If you don't include it, you'll get a warning in your browser console. For more on the `key` prop, check out the [React Docs: List and Keys](https://reactjs.org/docs/lists-and-keys.html#keys).)
+ ```js:title=src/pages/blog.js
+ // imports
+
+ const BlogPage = ({ data }) => {
+ return (
+
+ {/* highlight-start */} + { + data.allMdx.nodes.map((node) => ( + + ) + } + + export const query = graphql` + query { + allMdx(sort: {fields: frontmatter___date, order: DESC}) { + nodes { + frontmatter { + title + date(formatString: "MMMM DD, YYYY") + } + id + body + } + } + } + ` + + export default BlogPage + ``` + +3. Go to `localhost:8000/blog` in your web browser. You should be able to see the titles and dates for each of your posts: + + + +4. The final step in this part of the Tutorial is to render the actual contents of your MDX blog posts. To do that, you'll need to use a component from `gatsby-plugin-mdx` called `MDXRenderer`. Start by importing the component into your Blog page: + +```js:title=src/pages/blog.js +import * as React from 'react' +import { graphql } from 'gatsby' +import { MDXRenderer } from 'gatsby-plugin-mdx' // highlight-line +import Layout from '../components/layout' + +// ... +``` + ++ + )) + } + {/* highlight-end */} +{node.frontmatter.title}
+Posted: {node.frontmatter.date}
+The + +5. In the JSX for your Blog page, use the `MDXRenderer` component to wrap the contents of the `body` field for each node: + +```js:title=src/pages/blog.js +import * as React from 'react' +import { graphql } from 'gatsby' +import { MDXRenderer } from 'gatsby-plugin-mdx' +import Layout from '../components/layout' + +const BlogPage = ({ data }) => { + return ( +MDXRenderercomponent} +> + +`MDXRenderer` is a component included in the `gatsby-plugin-mdx` plugin that you can use to render the contents of a `.mdx` file. + +The `MDXRenderer` uses the `children` prop, similar to the `Layout` component you created in [Part 2](/docs/tutorial/part-2/). It expects to receive compiled MDX between the its opening and closing tags. You can pass in the `body` field from an MDX node. + ++ +**Quick Refresher:** Need a reminder of how the `children` prop works? Refer back to the ["Create a reusable layout component" section in Part 2](/docs/tutorial/part-2/#create-a-reusable-layout-component). + + + +Here's a quick example of how to import and use the `MDXRenderer` component: + +```js +import { MDXRenderer } from 'gatsby-plugin-mdx' + +// Use this in the JSX for your component ++ { node.body } + +``` + ++ { + data.allMdx.nodes.map((node) => ( + + ) +} + +export const query = graphql` + query { + allMdx(sort: {fields: frontmatter___date, order: DESC}) { + nodes { + frontmatter { + title + date(formatString: "MMMM DD, YYYY") + } + id + body + } + } + } +` + +export default BlogPage +``` + +6. When you refresh your Blog page in the web browser, you should see your post contents rendered! +  + +Nice work! Your site now has a blog page with actual content. + +## Summary + +Take a moment to think back on what you've learned so far. Challenge yourself to answer the following questions from memory: + +* What is a transformer plugin? How do transformer plugins affect the data in the data layer? +* What is MDX? Why is it useful? + ++ + )) + } +{node.frontmatter.title}
+Posted: {node.frontmatter.date}
+ {/* highlight-start */} ++ {node.body} + + {/* highlight-end */} ++ +**Ship It!** 🚀 + +Before you move on, deploy your changes to your live site on Gatsby Cloud so that you can share your progress! + +First, run the following commands in a terminal to push your changes to your GitHub repository. (Make sure you're in the top-level directory for your Gatsby site!) + +```shell +git add . +git commit -m "Finished Gatsby Tutorial Part 5" +git push +``` + +Once your changes have been pushed to GitHub, Gatsby Cloud should notice the update and rebuild and deploy the latest version of your site. (It may take a few minutes for your changes to be reflected on the live site. Watch your build's progress from your [Gatsby Cloud dashboard](/dashboard/).) + + + +### Key takeaways + +* Data in Gatsby's GraphQL data layer is stored in **nodes**. +* Each source plugin creates a different type of node with different fields. +* Transformer plugins create new types of nodes, using data from existing source nodes as a starting point. Transformer plugins don't actually change the original source nodes. +* `gatsby-plugin-mdx` is a transformer plugin that lets you use MDX in your site. With MDX, you can create text content with Markdown formatting and embedded React components. + ++ +**Share Your Feedback!** + +Our goal is for this Tutorial to be helpful and easy to follow. We'd love to hear your feedback about what you liked or didn't like about this part of the Tutorial. + +Use the "Was this doc helpful to you?" form at the bottom of this page to let us know what worked well and what we can improve. + + + +### What's coming next? + +Right now, all your blog posts and their contents are being rendered in one long page. It would be better if each post lived on its own page, and then the Blog page could link out to all the different posts. + +In Part 6, you'll learn how to use Gatsby's filesystem route API to dynamically create new pages for each of your blog posts. + ++ + Note: We{"'"}re still working on updating this Tutorial to use Gatsby v3. + You've reached the end of the new content we've released so far. Subsequent parts + will be added as we finish them. Part 6 has a tentative release date of July 28, 2021. +
++ If you{"'"}re looking for a full experience in the meantime, you can check out the (slightly outdated){" "} + + Gatsby v2 Tutorial + + . +
+ + } +/> diff --git a/docs/docs/tutorial/part-five/allfile-query.png b/docs/docs/tutorial/part-five/allfile-query.png deleted file mode 100644 index d0a457b47b1fc..0000000000000 Binary files a/docs/docs/tutorial/part-five/allfile-query.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/data-in-console.png b/docs/docs/tutorial/part-five/data-in-console.png deleted file mode 100644 index 7ece96f81420d..0000000000000 Binary files a/docs/docs/tutorial/part-five/data-in-console.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/filesystem-autocomplete.png b/docs/docs/tutorial/part-five/filesystem-autocomplete.png deleted file mode 100644 index f91668c1ba023..0000000000000 Binary files a/docs/docs/tutorial/part-five/filesystem-autocomplete.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/filesystem-explorer-options.png b/docs/docs/tutorial/part-five/filesystem-explorer-options.png deleted file mode 100644 index a4811a1d1474d..0000000000000 Binary files a/docs/docs/tutorial/part-five/filesystem-explorer-options.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/filesystem-query.png b/docs/docs/tutorial/part-five/filesystem-query.png deleted file mode 100644 index b6604116721da..0000000000000 Binary files a/docs/docs/tutorial/part-five/filesystem-query.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/graphiql-filesystem.png b/docs/docs/tutorial/part-five/graphiql-filesystem.png deleted file mode 100644 index b775e213b8f8c..0000000000000 Binary files a/docs/docs/tutorial/part-five/graphiql-filesystem.png and /dev/null differ diff --git a/docs/docs/tutorial/part-five/index.md b/docs/docs/tutorial/part-five/index.md deleted file mode 100644 index 5cafcfa3883ba..0000000000000 --- a/docs/docs/tutorial/part-five/index.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Source Plugins -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](/docs/tutorial/part-four/) before continuing here. - -## What's in this tutorial? - -In this tutorial, you'll be learning about how to pull data into your Gatsby site using GraphQL and source plugins. Before you learn about these plugins, however, you'll want to know how to use something called GraphiQL, a tool that helps you structure your queries correctly. - -## Introducing GraphiQL - -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 `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. - -## Using the GraphiQL Explorer - -The GraphiQL Explorer enables you to interactively construct full queries by clicking through available fields and inputs without the repetitive process of typing these queries out by hand. - -- -## Source plugins - -Data in Gatsby sites can come from anywhere: APIs, databases, CMSs, local files, etc. - -Source plugins fetch data from their source. E.g. the filesystem source plugin knows how to fetch data from the file system. The WordPress plugin knows how to fetch data from the WordPress API. - -Add [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/) and explore how it works. - -First, install the plugin at the root of the project: - -```shell -npm install gatsby-source-filesystem -``` - -Then add it to your `gatsby-config.js`: - -```javascript:title=gatsby-config.js -module.exports = { - siteMetadata: { - title: `Pandas Eating Lots`, - }, - plugins: [ - // highlight-start - { - resolve: `gatsby-source-filesystem`, - options: { - name: `src`, - path: `${__dirname}/src/`, - }, - }, - // highlight-end - `gatsby-plugin-emotion`, - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography`, - }, - }, - ], -} -``` - -Save that and restart the gatsby development server. Then open up GraphiQL again. - -In the explorer pane, you'll see `allFile` and `file` available as selections: - - - -Click the `allFile` dropdown. Position your cursor after `allFile` in the query area, and then type Ctrl + Enter. This will pre-fill a query for the `id` of each file. Press "Play" to run the query: - - - -In the Explorer pane, the `id` field has automatically been selected. Make selections for more fields by checking the field's corresponding checkbox. Press "Play" to run the query again, with the new fields: - - - -Alternatively, you can add fields by using the autocomplete shortcut (Ctrl + Space). This will show queryable fields on the `File` nodes. - - - -Try adding a number of fields to your query, press Ctrl + Enter 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. - -## Build a page with a GraphQL query - -Building new pages with Gatsby often starts in GraphiQL. You first sketch out the data query by playing in GraphiQL then copy this to a React page component to start building the UI. - -Let's try this. - -Create a new file at `src/pages/my-files.js` with the `allFile` GraphQL query you just -created: - -```jsx:title=src/pages/my-files.js -import React from "react" -import { graphql } from "gatsby" -import Layout from "../components/layout" - -export default function MyFiles({ data }) { - console.log(data) // highlight-line - return ( - - - ) -} - -export const query = graphql` - query { - allFile { - edges { - node { - relativePath - prettySize - extension - birthTime(fromNow: true) - } - } - } - } -` -``` - -The `console.log(data)` line is highlighted above. It's often helpful when creating a new component to console out the data you're getting from the GraphQL query so you can explore the data in your browser console while building the UI. - -If you visit the new page at `/my-files/` and open up your browser console you will see something like: - - - -The shape of the data matches the shape of the GraphQL query. - -Add some code to your component to print out the File data. - -```jsx:title=src/pages/my-files.js -import React from "react" -import { graphql } from "gatsby" -import Layout from "../components/layout" - -export default function MyFiles({ data }) { - console.log(data) - return ( -Hello world-- {/* highlight-start */} - - ) -} - -export const query = graphql` - query { - allFile { - edges { - node { - relativePath - prettySize - extension - birthTime(fromNow: true) - } - } - } - } -` -``` - -And now visit `http://localhost:8000/my-files`… 😲 - - - -## What's coming next? - -Now you've learned how source plugins bring data _into_ Gatsby’s data system. In the next tutorial, you'll learn how transformer plugins _transform_ the raw content brought by source plugins. The combination of source plugins and transformer plugins can handle all data sourcing and data transformation you might need when building a Gatsby site. Learn about transformer plugins in [part six of the tutorial](/docs/tutorial/part-six/). diff --git a/docs/docs/tutorial/part-five/my-files-page.png b/docs/docs/tutorial/part-five/my-files-page.png deleted file mode 100644 index 17467af4ca70f..0000000000000 Binary files a/docs/docs/tutorial/part-five/my-files-page.png and /dev/null differ diff --git a/docs/docs/tutorial/part-four/index.md b/docs/docs/tutorial/part-four/index.md deleted file mode 100644 index 59279f0471472..0000000000000 --- a/docs/docs/tutorial/part-four/index.md +++ /dev/null @@ -1,359 +0,0 @@ ---- -title: Data in Gatsby -typora-copy-images-to: ./ -disableTableOfContents: true ---- - -Welcome to Part Four of the tutorial! Halfway through! Hope things are starting 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 create your _own_ components to act as custom building blocks for websites. - -You’ve also explored styling components using CSS Modules. - -## What's in this tutorial? - -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 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/). - -## 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?** - -A very computer science-y answer would be: data is things like `"strings"`, integers (`42`), objects (`{ pizza: true }`), etc. - -For the purpose of working in Gatsby, however, a more useful answer is "everything that lives outside a React component". - -So far, you've been writing text and adding images _directly_ in components. Which is an _excellent_ way to build many websites. But, often you want to store data _outside_ components and then bring the data _into_ the component as needed. - -If you're building a site with WordPress (so other contributors have a nice interface for adding & maintaining content) and Gatsby, the _data_ for the site (pages and posts) are in WordPress and you _pull_ that data, as needed, into your components. - -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. - -## Using Unstructured Data vs GraphQL - -### Do I have to use GraphQL and source plugins to pull data into Gatsby sites? - -Absolutely not! You can use the node `createPages` API to pull unstructured data into Gatsby pages directly, rather than through the GraphQL data layer. This is a great choice for small sites, while GraphQL and source plugins can help save time with more complex sites. - -See the [Using Gatsby without GraphQL](/docs/how-to/querying-data/using-gatsby-without-graphql/) guide to learn how to pull data into your Gatsby site using the node `createPages` API and to see an example site! - -### When do I use unstructured data vs GraphQL? - -If you're building a small site, one efficient way to build it is to pull in unstructured data as outlined in this guide, using `createPages` API, and then if the site becomes more complex later on, you move on to building more complex sites, or you'd like to transform your data, follow these steps: - -1. Check out the [Plugin Library](/plugins/) to see if the source plugins and/or transformer plugins you'd like to use already exist -2. If they don't exist, read the [Plugin Authoring](/docs/creating-plugins/) guide and consider building your own! - -### How Gatsby's data layer uses GraphQL to pull data into components - -There are many options for loading data into React components. One of the most popular and powerful of these is a technology called [GraphQL](https://graphql.org/). - -GraphQL was invented at Facebook to help product engineers _pull_ needed data into components. - -GraphQL is a **q**uery **l**anguage (the _QL_ part of its name). If you're familiar with SQL, it works in a very similar way. Using a special syntax, you describe the data you want in your component and then that data is given to you. - -Gatsby uses GraphQL to enable components to declare the data they need. - -## Create a new example site - -Create another new site for this part of the tutorial. You're going to build a Markdown blog called "Pandas Eating Lots". It's dedicated to showing off the best pictures and videos of pandas eating lots of food. Along the way, you'll be dipping your toes into GraphQL and Gatsby's Markdown support. - -Open a new terminal window and run the following commands to create a new Gatsby site in a directory called `tutorial-part-four`. Then navigate to the new directory: - -```shell -gatsby new tutorial-part-four https://github.com/gatsbyjs/gatsby-starter-hello-world -cd tutorial-part-four -``` - -Then install some other needed dependencies at the root of the project. You'll use the Typography theme "Kirkham", and you'll try out a CSS-in-JS library, ["Emotion"](https://emotion.sh/): - -```shell -npm install gatsby-plugin-typography typography react-typography typography-theme-kirkham gatsby-plugin-emotion @emotion/react -``` - -Set up a site similar to what you ended with in [Part Three](/docs/tutorial/part-three). This site will have a layout component and two page components: - -```jsx:title=src/components/layout.js -import React from "react" -import { css } from "@emotion/react" -import { Link } from "gatsby" - -import { rhythm } from "../utils/typography" - -export default function Layout({ children }) { - return ( --- {/* highlight-end */} -My Site's Files
-- -
-- - - - {data.allFile.edges.map(({ node }, index) => ( -relativePath -prettySize -extension -birthTime -- - ))} - -{node.relativePath} -{node.prettySize} -{node.extension} -{node.birthTime} -- -- ) -} -``` - -```jsx:title=src/pages/index.js -import React from "react" -import Layout from "../components/layout" - -export default function Home() { - return ( -- Pandas Eating Lots -
- - - About - - {children} -- - ) -} -``` - -```jsx:title=src/pages/about.js -import React from "react" -import Layout from "../components/layout" - -export default function About() { - return ( -Amazing Pandas Eating Things
---
- - - ) -} -``` - -```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: - - - -You have another small site with a layout and two pages. - -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). - -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. - -The place for these common bits of data is the `siteMetadata` object in the `gatsby-config.js` file. Add your site title to the `gatsby-config.js` file: - -```javascript:title=gatsby-config.js -module.exports = { - // highlight-start - siteMetadata: { - title: `Title from siteMetadata`, - }, - // highlight-end - plugins: [ - `gatsby-plugin-emotion`, - { - resolve: `gatsby-plugin-typography`, - options: { - pathToConfigModule: `src/utils/typography`, - }, - }, - ], -} -``` - -Restart the development server. - -### Use a page query - -Now the site title is available to be queried; Add it to the `about.js` file using a [page query](/docs/how-to/querying-data/page-query): - -```jsx:title=src/pages/about.js -import React from "react" -import { graphql } from "gatsby" // highlight-line -import Layout from "../components/layout" - -// highlight-next-line -export default function About({ data }) { - return ( -About Pandas Eating Lots
-- We're the only site running on your computer dedicated to showing the - best photos and videos of pandas eating lots of food. -
-- - ) -} - -// highlight-start -export const query = graphql` - query { - site { - siteMetadata { - title - } - } - } -` -// highlight-end -``` - -It worked! 🎉 - - - -The basic GraphQL query that retrieves the `title` in your `about.js` changes above is: - -```graphql:title=src/pages/about.js -{ - site { - siteMetadata { - title - } - } -} -``` - -> 💡 In [part five](/docs/tutorial/part-five/#introducing-graphiql), you'll meet a tool that lets us interactively explore the data available through GraphQL, and help formulate queries like the one above. - -Page queries live outside of the component definition -- by convention at the end of a page component file -- and are only available on page components. - -### Use a StaticQuery - -[StaticQuery](/docs/how-to/querying-data/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/how-to/querying-data/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: - -```jsx:title=src/components/layout.js -import React from "react" -import { css } from "@emotion/react" -// highlight-next-line -import { useStaticQuery, Link, graphql } from "gatsby" - -import { rhythm } from "../utils/typography" -// highlight-start -export default function Layout({ children }) { - const data = useStaticQuery( - graphql` - query { - site { - siteMetadata { - title - } - } - } - ` - ) - return ( - // highlight-end -About {data.site.siteMetadata.title}
{/* highlight-line */} -- We're the only site running on your computer dedicated to showing the - best photos and videos of pandas eating lots of food. -
-- -- // highlight-start - ) -} -// highlight-end -``` - -Another success! 🎉 - - - -Why use two different queries here? These examples were quick introductions to the query types, how they are formatted, and where they can be used. For now, keep in mind that only pages can make page queries. Non-page components, such as Layout, can use StaticQuery. [Part 7](/docs/tutorial/part-seven/) of the tutorial explains these in greater depth. - -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. - - - -## What's coming next? - -Next, you'll be learning about how to pull data into your Gatsby site using GraphQL with source plugins in [part five](/docs/tutorial/part-five/) of the tutorial. diff --git a/docs/docs/tutorial/part-four/pandas-eating-lots-titles.png b/docs/docs/tutorial/part-four/pandas-eating-lots-titles.png deleted file mode 100644 index 64d209363ea8e..0000000000000 Binary files a/docs/docs/tutorial/part-four/pandas-eating-lots-titles.png and /dev/null differ diff --git a/docs/docs/tutorial/part-four/site-metadata-title.png b/docs/docs/tutorial/part-four/site-metadata-title.png deleted file mode 100644 index 942947eeca087..0000000000000 Binary files a/docs/docs/tutorial/part-four/site-metadata-title.png and /dev/null differ diff --git a/docs/docs/tutorial/part-four/site-metadata-two-titles.png b/docs/docs/tutorial/part-four/site-metadata-two-titles.png deleted file mode 100644 index 86f498fcf6313..0000000000000 Binary files a/docs/docs/tutorial/part-four/site-metadata-two-titles.png and /dev/null differ diff --git a/docs/docs/tutorial/part-four/start.png b/docs/docs/tutorial/part-four/start.png deleted file mode 100644 index 2591cff41c04b..0000000000000 Binary files a/docs/docs/tutorial/part-four/start.png and /dev/null differ- {data.site.siteMetadata.title} {/* highlight-line */} -
- - - About - - {children} -