diff --git a/docs/docs/wordpress-source-plugin-tutorial.md b/docs/docs/wordpress-source-plugin-tutorial.md new file mode 100644 index 0000000000000..8f2350b46205d --- /dev/null +++ b/docs/docs/wordpress-source-plugin-tutorial.md @@ -0,0 +1,156 @@ +## How to create a site with data pulled from WordPress + +### What this tutorial covers: + +In this tutorial, you will install the `gatsby-source-wordpress` plugin in order to pull blog and image data from a WordPress install into your Gatsby site and render that data. This [Gatsby + Wordpress demo site](https://using-wordpress.gatsbyjs.org/) shows you a sample of what you’re going to be building in this tutorial., although it’s missing the cool images you’ll be adding :D + +### Why go through this tutorial? + +While each source plugin may operate differently from others, it’s worth going through this tutorial because you will almost definitely be using a source plugin in most Gatsby sites you build. This tutorial will walk you through the basics of connecting your Gatsby site to a CMS, pulling in data, and using React to render that data in beautiful ways on your site. + +If you’d like to look at the growing number source plugins available to you, search for “source” in the [Gatsby plugin library](/plugins/?=source). + +### Creating a site with the `gatsby-source-wordpress` plugin + +Create a new Gatsby project and change directories into the new project you just created: + +```shell +gatsby new wordpress-tutorial-site +cd wordpress-tutorial-site +``` + +Install the `gatsby-source-wordpress` plugin. For extra reading on the plugin’s features and examples of GraphQL queries not included in this tutorial, see the [`gatsby-source-wordpress` plugin’s READme file](/packages/gatsby-source-wordpress/?=wordpress). + +```shell +npm install --save gatsby-source-wordpress +``` + +Add the `gatsby-source-wordpress` plugin to `gatsby-config.js` using the following code, which you can also find in the [demo site’s source code](https://github.com/gatsbyjs/gatsby/blob/master/examples/using-wordpress/gatsby-config.js). + +```javascript{32-58} + module.exports = { + siteMetadata: { + title: 'Gatsby Wordpress Tutorial', + }, + plugins: [ + // https://public-api.wordpress.com/wp/v2/sites/gatsbyjsexamplewordpress.wordpress.com/pages/ + /* + * Gatsby's data processing layer begins with “source” + * plugins. Here the site sources its data from Wordpress. + */ + { + resolve: `gatsby-source-wordpress`, + options: { + /* + * The base URL of the Wordpress site without the trailingslash and the protocol. This is required. + * Example : 'gatsbyjswpexample.wordpress.com' or 'www.example-site.com' + */ + baseUrl: `dev-gatbsyjswp.pantheonsite.io`, + // The protocol. This can be http or https. + protocol: `http`, + // Indicates whether the site is hosted on wordpress.com. + // If false, then the asumption is made that the site is self hosted. + // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2. + // If your site is hosted on wordpress.org, then set this to false. + hostingWPCOM: false, + // If useACF is true, then the source plugin will try to import the Wordpress ACF Plugin contents. + // This feature is untested for sites hosted on Wordpress.com + useACF: true, + }, + }, + ], +} +``` + +### Creating GraphQL queries that pull data from WordPress + +Now you are ready to create a GraphQL query to pull in some data from the WordPress site. You will create a query that pulls in the title of the blogposts, date they were posted, and blogpost content. + +Run: + +```shell +gatsby develop +``` + +Open localhost:8000 and localhost:8000/__graphql. + +This query will pull in the blogpost content from WordPress: + +```graphql +query { + allWordpressPage { + edges { + node { + id + title + excerpt + slug + date(formatString: "MMMM DD, YYYY") + } + } + } +} +``` + + +This query will pull in a sorted list of those blogposts: + +```graphql +{ + allWordpressPost(sort: { fields: [date] }) { + edges { + node { + title + excerpt + Slug + ...PostIcons + } + } + } +} +``` + + +### Rendering the blogposts to `index.js` + +Here is what your `index.js` should look like: + +```jsx +import React from 'react' + +export default ({ data }) => { + console.log(data) + return ( +
{node.title}
+{node.excerpt}
+