gatsby-theme-headless-wordpress
π‘ What does it do?
This plugin handles creating pages in Gatsby for all of the content sourced by gatsby-source-wordpress.
π Quick start
Use my starter project gatsby-starter-headless-wordpress or follow the getting started section for gatsby-source-wordpress
Install and add the theme to your gatsby-config.js
yarn add gatsby-theme-headless-wordpress gatsby-source-wordpress
Minimal gatsby-config setup
module.exports = {
plugins: [
{
resolve: `gatsby-source-wordpress`,
options: {
// the only required plugin option for WordPress is the GraphQL url.
url:
process.env.WPGRAPHQL_URL ||
`https://wpgatsbydemo.wpengine.com/graphql`,
},
},
`gatsby-theme-headless-wordpress`, // no plugin options are required
],
}
Plugin Options
{
resolve: `gatsby-theme-headless-wordpress`
options: {
templatesPath: `./src/templates`, // default ~ the folder where you will keep your page template files
excludedNodeTypes: [`MediaItem`], // default ~ excludes creating pages for individual media items
type: {
__all: { // '__all' will override options for all post types
postsPerPage: 999
},
post: { // 'post' will override options for a specific post type, matching by graphqlSingleName
postsPerPage: 999
},
page: { // 'page' will override options for a specific post type, matching by graphqlSingleName
postsPerPage: 999
},
anyCustomPostType: { // 'anyCustomPostType' will override options for a specific post type, matching by graphqlSingleName
postsPerPage: 999
},
category: { // 'category' will override options for the specific taxonomy term node
postsPerPage: 999
},
tag: { // 'tag' will override options for that specific taxonomy term node
postsPerPage: 999
},
anyCustomTaxonomy: { // 'customTaxonomy' will override options for that specific taxonomy term node
postsPerPage: 999
},
}
}
}
Compatibility
Currently supports WP templates, pages, posts, archive pages, taxonomies (tags, categories, custom taxonomies), custom post types, and custom post type archives.
If the WPGraphQL Yoast SEO Addon is installed in WordPress, this plugin will query the seo data for each node and pass it to the page context. { pageContext: { seo } }
πTemplates
To use different templates for a single post type, a template must be assigned to the page/post in WP.
The template files will follow this folder structure with camel cased names. Supports any file extension. (.js, .jsx, .ts, .tsx)
.
βββ src
βββ templates
βββ page // post type graphqlSingleName
βββ default.tsx
βββ fullWidth.tsx // name of the template assigned to the page in WP (camelCased)
βββ post
βββ default.tsx
βββ archive
βββ post.tsx // post type graphqlSingleName
βββ product.tsx
βββ taxonomy
βββ category.tsx
βββ tag.tsx
βββ customTaxonomyName.tsx
Pages, Posts, and Custom post types:
${pluginOptions.templatesPath}/${postType graphqlSingleName}/${templateName}
Taxonomies:
${pluginOptions.templatesPath}/taxonomy/${taxonomy.name}
Archive pages:
${pluginOptions.templatesPath}/archive/${postType graphqlSingleName}
Roadmap
Support CPT archive pages- β Completed in 0.1.0- Add options to pass additional data to page context - π₯In progress
- Add options to have more control over the templates folder structure
- Allow more generic page components to be used across different post types similar to WP template hierarchy
Sites using this plugin
- https://jambaree.com/
- https://www.thedeckingsuperstore.com/
- https://polarbattery.com/
- https://walkerbay.com/
Did you use this plugin in a website? Open a pull request and add to this list.
Changelog
0.1.9
- fixed taxonomy query issue that was introduced in 0.1.8
0.1.8
- fixed issue with taxonomy archive pagination. Now taxonomy pages will paginate correctly.
- added the ability to override
postsPerPage
for taxonomy archive pages, similar to how you would overridepostsPerPage
for normal archive pages. - Tested with WPGraphQL 1.6.12 and WPGatsby 2.1.1
0.1.7
- added plugin options to override
postsPerPage
for specific post types or globally. - Tested with WPGraphQL 1.4.3 and WPGatsby 1.0.10
0.1.6
- added
archivePath
to pageContext for single pages. Now single pages can link back to the archive page OR use this uri to query data from the archive page.
0.1.5
- added
currentPage
to pageContext for archive pages and taxonomy pages. Used to help with pagination in page templates.
0.1.4
- added
totalPages
to pageContext for archive pages and taxonomy pages. This is to help with page templates that need more advanced pagination than just prev/next buttons.
0.1.1
- fixed bug that caused the home page to become the posts page even if no posts archive was set in WP
0.1.0
- added support for all post type archives, previous versions only support the /blog/ archive for the default βpostβ type