docs: Create a custom WordPress sitemap with custom WP-GQL endpoint

[ahuseyn]

Related to: #30

The example includes the @colinmurphy's implementation of wp-env, with custom data and plugins

Which parts need focused attention?

hwpt-wpgraphql-sitemap needs focused attention

---

Overview

This example demonstrates how to generate a custom sitemap in a headless WordPress application using the Next.js framework. The example app fetches data from WordPress using Apollo Client and WPGraphQL. Since WPGraphQL doesn't support sitemaps natively, we are extending it with a custom plugin, which is included in this example as well. This plugin exposes new fields to fetch the sitemap index, with data identical to what's rendered on the native WordPress sitemap. Another field exposed by this plugin allows you to request sitemap subpages by specifying the types and pages. The plugin also adds featured image data, enabling you to create Image Sitemaps.

The example includes a wp-env setup, which will allow you to build and start this example quickly. With this wp-env setup, you don't need to have a separate WordPress instance or demo data to inspect the example.

Features

1. Fetching sitemap data with the API allows maximum customizability
2. Custom plugin to extend WPGraphQL with the sitemap feature
3. Plugin uses native WordPress sitemap hooks and methods for security and performance
4. An identical WordPress sitemap structure in the headless setup
5. Image Sitemaps implementation
6. Configured WordPress instance with demo data and required plugins, using wp-env
7. Sitemaps for custom post and taxonomy types
8. Permanent redirect of /sitemap requests to /sitemap.xml, in the next.config.mjs

Screenshots

After following the installation steps, you should have the example sitemap pages as shown in the screenshots below:

Sitemap index	Posts
Categories	Tags
Users	Pages
Custom post type	Custom taxonomy type

Project Structure

├── example-app                                # Next.js application root
│   ├── public
│   │   └── sitemap.xsl                        # XSLT style file for the sitemap
│   └── src
│       ├── components
│       ├── lib
│       │   ├── client.js                      # Apollo Client instance
│       │   └── generateSiteMap.js             # Helper function that generates the XML content
│       └── pages
│           ├── sitemap                        # Base path for sitemap subpages
│           │   └── [...type]                  # Catch-all route for sitemap subpages
│           └── sitemap.xml.js                 # Index sitemap.xml page
├── hwpt-wpgraphql-sitemap                     # PHP files for the HWPT WPGraphQL Sitemap plugin
├── hwpt-wpgraphql-sitemap.zip                 # HWPT WPGraphQL Sitemap plugin to enable sitemap fields
├── .wp-env.json                               # wp-env configuration file
└── wp-env
    ├── db
    │   └── database.sql                       # WordPress database including all demo data for the example
    └── uploads.zip                            # WordPress content to be used by wp-env

Important notes

• If you're intending to use this example with your own WordPress instance, make sure to uncheck the Discourage search engines from indexing this site checkbox under Settings -> Reading in the WordPress admin.
• If the XML sitemap feature in Yoast SEO is enabled, it will disable the native WordPress sitemap. To run this example, you must disable Yoast SEO's XML sitemap feature.

Running the example with wp-env

Prerequisites

• Node.js (v18+ recommended)
• pnpm
• Docker (if you plan on running the example see details below)

Note Please make sure you have all prerequisites installed as mentioned above and Docker running (docker ps)

Setup Repository and Packages

• Clone the repo git clone https://github.com/wpengine/hwptoolkit.git
• Install packages `cd hwptoolkit && pnpm install
• Setup a .env file under examples/next/custom-sitemap-apollo/example-app and add these values inside:

NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
NEXT_PUBLIC_URL=http://localhost:3000

or run the command below:

echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888\\nNEXT_PUBLIC_URL=http://localhost:3000" > examples/next/custom-sitemap-apollo/example-app/.env

Build and start the application

• cd examples/next/custom-sitemap-apollo
• Then run pnpm example:build will build and start your application.
• This does the following:
  • Unzips wp-env/uploads.zip to wp-env/uploads which is mapped to the wp-content/uploads directory for the Docker container.
  • Starts up wp-env
  • Imports the database from wp-env/db/database.sql
  • Install Next.js dependencies for example-app
  • Runs the Next.js dev script

Congratulations, WordPress should now be fully set up.

Frontend	Admin
http://localhost:3000/	http://localhost:8888/wp-admin/

Note: The login details for the admin is username "admin" and password "password"

Command Reference

Command	Description
example:build	Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application.
example:dev	Runs the Next.js development server.
example:dev:install	Installs the required Next.js packages.
example:start	Starts WordPress and the Next.js development server.
example:stop	Stops the WordPress environment.
example:prune	Rebuilds and restarts the application by destroying and recreating the WordPress environment.
wp:start	Starts the WordPress environment.
wp:stop	Stops the WordPress environment.
wp:destroy	Completely removes the WordPress environment.
wp:db:query	Executes a database query within the WordPress environment.
wp:db:export	Exports the WordPress database to wp-env/db/database.sql.
wp:db:import	Imports the WordPress database from wp-env/db/database.sql.
wp:images:unzip	Extracts the WordPress uploads directory.
wp:images:zip	Compresses the WordPress uploads directory.

Note You can run pnpm wp-env and use any other wp-env command. You can also see https://www.npmjs.com/package/@wordpress/env for more details on how to use or configure wp-env.

Database access

If you need database access add the following to your wp-env "phpmyadminPort": 11111, (where port 11111 is not allocated).

You can check if a port is free by running lsof -i :11111

[colinmurphy]

@ahuseyn 🚀 🚀 🚀

LGTM.

Just want to call out and say this is very impressive. The sitemaps look good to me.

I also validated them with xmllint

e.g.

xmllint --noout --debug http://localhost:3000/sitemap/posts/post/1.xml
xmllint --noout --debug http://localhost:3000/sitemap.xml   

[ahuseyn]

Thanks @colinmurphy, I appreciate it 🙂

[moonmeister]

Looking good, I think we still need to decide how to address what was expected for this ticket vs this approach. Let's talk tomorrow during refinement.

[moonmeister]

I'm approving this for general acceptance criteria and content. I have not actually tested and run the code. I think this looks good. I'm debating whether we should have the catch-all route. given this is only suppose to be demonstrating sitemaps, do we ned to render pages? IS it a distraction? but also a front-end with no actual content is kinda weird. I'll leave it to you.

[ahuseyn]

@moonmeister I gave a thought to rendering pages, and experimented with/without it. Without rendering pages the example looked incomplete/partial as the final sitemap links were breaking. Thus I wanted to add a single catch-all route to minimize the distraction.