From ad6125b66c49fff4973056ca39b800801a35c86c Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Thu, 23 Oct 2025 16:41:07 +0100 Subject: [PATCH 1/4] Updated paths for toolkti nav.json to be /toolkit/ not /docs/ --- docs/nav.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/nav.json b/docs/nav.json index e6d0c2bd..51a1f1d9 100644 --- a/docs/nav.json +++ b/docs/nav.json @@ -1,49 +1,49 @@ [ { "title": "Introduction", - "route": "/docs/" + "route": "/toolkit/" }, { "title": "Explanation", - "route": "/docs/explanation/", + "route": "/toolkit/explanation/", "children": [ { "title": "GET vs POST", - "route": "/docs/explanation/get-vs-post/" + "route": "/toolkit/explanation/get-vs-post/" }, { "title": "GraphQL Endpoints", - "route": "/docs/explanation/graphql-endpoints/" + "route": "/toolkit/explanation/graphql-endpoints/" }, { "title": "Headless Authentication", - "route": "/docs/explanation/headless-authentication/" + "route": "/toolkit/explanation/headless-authentication/" }, { "title": "Rendering Options", - "route": "/docs/explanation/rendering-options/" + "route": "/toolkit/explanation/rendering-options/" }, { "title": "Routing", - "route": "/docs/explanation/routing/" + "route": "/toolkit/explanation/routing/" }, { "title": "Sitemaps", - "route": "/docs/explanation/sitemaps/" + "route": "/toolkit/explanation/sitemaps/" } ] }, { "title": "How-To Guides", - "route": "/docs/how-to/", + "route": "/toolkit/how-to/", "children": [ { "title": "Install Toolkit Plugins via Composer", - "route": "/docs/how-to/install-toolkit-plugins/" + "route": "/toolkit/how-to/install-toolkit-plugins/" }, { "title": "Automatic Persisted Queries in Next.js", - "route": "/docs/how-to/nextjs-pages-router/enable-apq/" + "route": "/toolkit/how-to/nextjs-pages-router/enable-apq/" } ] } From ab6c16b33c0152d7152ed081369878b600d67b88 Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Thu, 23 Oct 2025 17:42:00 +0100 Subject: [PATCH 2/4] Add frontmatter metadata to documentation guides Introduced YAML frontmatter to multiple documentation files, specifying title and description for improved SEO and content organization. This change enhances discoverability and provides clearer context for each guide. --- docs/explanation/get-vs-post.md | 5 +++++ docs/explanation/graphql-endpoints.md | 5 +++++ docs/explanation/headless-authentication.md | 5 +++++ docs/explanation/rendering-options.md | 5 +++++ docs/explanation/routing.md | 5 +++++ docs/explanation/sitemaps.md | 5 +++++ docs/how-to/install-toolkit-plugins/index.md | 5 +++++ docs/how-to/nextjs-pages-router/enable-apq/index.md | 5 +++++ 8 files changed, 40 insertions(+) diff --git a/docs/explanation/get-vs-post.md b/docs/explanation/get-vs-post.md index 89961336..2e6e6538 100644 --- a/docs/explanation/get-vs-post.md +++ b/docs/explanation/get-vs-post.md @@ -1,3 +1,8 @@ +--- +title: "GET vs POST in WPGraphQL" +description: "A guide on the differences between using a GET request with a query parameter versus a POST request to the /graphql endpoint." +--- + # GET vs POST in WPGraphQL When interacting with WPGraphQL, selecting the correct HTTP method to fetch data is crucial. This guide explains the differences between using a GET request with a query parameter versus a POST request to the /graphql endpoint. diff --git a/docs/explanation/graphql-endpoints.md b/docs/explanation/graphql-endpoints.md index de92b6fe..1defcea7 100644 --- a/docs/explanation/graphql-endpoints.md +++ b/docs/explanation/graphql-endpoints.md @@ -1,3 +1,8 @@ +--- +title: "WPGraphQL Endpoints" +description: "A guide on the differences between using /graphql and ?graphql WPGraphQL endpoints and how to customize them." +--- + # Which WPGraphQL endpoints to use: /graphql vs ?graphql WPGraphQL exposes a GraphQL endpoint that developers can use to interact with the WordPress backend and retrieve data. diff --git a/docs/explanation/headless-authentication.md b/docs/explanation/headless-authentication.md index 89a524f5..6dd404b7 100644 --- a/docs/explanation/headless-authentication.md +++ b/docs/explanation/headless-authentication.md @@ -1,3 +1,8 @@ +--- +title: "Headless Authentication" +description: "A guide on the process of verifying user identity and managing access control in a decoupled architecture where the WordPress and the frontend are separate systems." +--- + # What is headless authentication? Headless authentication refers to the process of verifying user identity and managing access control in a decoupled architecture where the content management system (WordPress) and the user-facing frontend are separate systems. Unlike traditional WordPress sites where authentication happens within a single application, headless authentication must work across systems, that may be located accross different regions. diff --git a/docs/explanation/rendering-options.md b/docs/explanation/rendering-options.md index 74d6d939..78c14a20 100644 --- a/docs/explanation/rendering-options.md +++ b/docs/explanation/rendering-options.md @@ -1,3 +1,8 @@ +--- +title: "Headless WordPress Rendering Options" +description: "A guide that explores the various approaches to rendering content from a headless WordPress installation, their trade-offs, and best practices." +--- + # Headless WordPress Rendering Options ## Introduction diff --git a/docs/explanation/routing.md b/docs/explanation/routing.md index f38a1423..8030c8c6 100644 --- a/docs/explanation/routing.md +++ b/docs/explanation/routing.md @@ -1,3 +1,8 @@ +--- +title: "Routing in Headledd WordPress" +description: "A guide that explores the intricacies of implementing routing in a headless WordPress setup. It covers the core challenges, possible implementations, and advanced considerations for optimizing your headless WordPress site." +--- + # Routing in Headless WordPress: A Comprehensive Guide This guide explores the intricacies of implementing routing in a headless WordPress setup. We'll cover the core challenges, possible implementations, and advanced considerations for optimizing your headless WordPress site. diff --git a/docs/explanation/sitemaps.md b/docs/explanation/sitemaps.md index c87ce994..9f327f0c 100644 --- a/docs/explanation/sitemaps.md +++ b/docs/explanation/sitemaps.md @@ -1,3 +1,8 @@ +--- +title: "Sitemaps in Headless WordPress" +description: "A guide on sitemaps in headless WordPress. It explains the challenges, and the different implementation approaches for sitemap generation." +--- + # Sitemaps in WordPress: A Comprehensive Overview ## What is a Sitemap? diff --git a/docs/how-to/install-toolkit-plugins/index.md b/docs/how-to/install-toolkit-plugins/index.md index ea0e08e2..17fbfbd7 100644 --- a/docs/how-to/install-toolkit-plugins/index.md +++ b/docs/how-to/install-toolkit-plugins/index.md @@ -1,3 +1,8 @@ +--- +title: "Installing HWP Toolkit Plugins with Composer" +description: "A guide on how to install any HWP Toolkit plugin using Composer, which is the recommended way for modern WordPress development workflows." +--- + # Installing HWP Toolkit Plugins with Composer You can install any HWP Toolkit plugin using Composer, which is the recommended way for modern WordPress development workflows. diff --git a/docs/how-to/nextjs-pages-router/enable-apq/index.md b/docs/how-to/nextjs-pages-router/enable-apq/index.md index 3426d65e..92977474 100644 --- a/docs/how-to/nextjs-pages-router/enable-apq/index.md +++ b/docs/how-to/nextjs-pages-router/enable-apq/index.md @@ -1,3 +1,8 @@ +--- +title: "Enable Automatic Persisted Queries in Next.js Pages Router" +description: "Learn how to reduce latency and network strain in GraphQL queries using Automatic Persisted Queries (APQ) by hashing and reusing query hashes." +--- + ## Overview GraphQL queries can use very detailed and long queries to get the appropriate data fields. These queries can increase the latency and put strain on the network. Automatic Persisted Queries (APQ) provides an effective solution to this issue, by hashing the queries and sending the hashes for repeated queries instead of sending the full query string. From 208bb909853d0bb0cf8c1f7f30f23ecf85af6776 Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Thu, 23 Oct 2025 19:07:22 +0100 Subject: [PATCH 3/4] Added new key value for being able to help determine the Github Raw URL when parsing. --- docs/nav.json | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/nav.json b/docs/nav.json index 51a1f1d9..13476c53 100644 --- a/docs/nav.json +++ b/docs/nav.json @@ -9,27 +9,33 @@ "children": [ { "title": "GET vs POST", - "route": "/toolkit/explanation/get-vs-post/" + "route": "/toolkit/explanation/get-vs-post/", + "append": ".md" }, { "title": "GraphQL Endpoints", - "route": "/toolkit/explanation/graphql-endpoints/" + "route": "/toolkit/explanation/graphql-endpoints/", + "append": ".md" }, { "title": "Headless Authentication", - "route": "/toolkit/explanation/headless-authentication/" + "route": "/toolkit/explanation/headless-authentication/", + "append": ".md" }, { "title": "Rendering Options", - "route": "/toolkit/explanation/rendering-options/" + "route": "/toolkit/explanation/rendering-options/", + "append": ".md" }, { "title": "Routing", - "route": "/toolkit/explanation/routing/" + "route": "/toolkit/explanation/routing/", + "append": ".md" }, { "title": "Sitemaps", - "route": "/toolkit/explanation/sitemaps/" + "route": "/toolkit/explanation/sitemaps/", + "append": ".md" } ] }, From 21b9d08adf1a511c396651d7cb58b1cb84b9513e Mon Sep 17 00:00:00 2001 From: Colin Murphy Date: Thu, 23 Oct 2025 20:06:53 +0100 Subject: [PATCH 4/4] Add index.md files for both explanations and how to guides. --- docs/explanation/index.md | 13 +++++++++++++ docs/how-to/index.md | 13 +++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 docs/explanation/index.md create mode 100644 docs/how-to/index.md diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 00000000..b231dd06 --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,13 @@ +--- +title: "Explanation" +description: "High-level conceptual guides that provide background information and understanding of Headless WordPress development with the Headless WordPress Toolkit." +--- + +I see you found the root of the Explanatory guides! Explanatory guides are a place where we step away from code and talk high-level concepts and import background information. If you are looking to grow your understanding of Headless WordPress with the toolkit, you are in the right place. + +> [!note] Learn More +> For more info on how we layout our documentation and the the role played by Explanatory Guides, please read about the [_Diátaxis_](https://diataxis.fr/explanation/) approach we use. + +## Contributing + +If you feel like something is missing or you want to add documentation, we encourage you to contribute! Please check out our [Contributing Guide](https://github.com/wpengine/hwptoolkit/blob/main/CONTRIBUTING.md) for more details. diff --git a/docs/how-to/index.md b/docs/how-to/index.md new file mode 100644 index 00000000..a0923da0 --- /dev/null +++ b/docs/how-to/index.md @@ -0,0 +1,13 @@ +--- +title: "How-to Guides" +description: "Step-by-step guides for implementing specific features and achieving practical goals with the Headless WordPress Toolkit." +--- + +I see you found the root of the How-to guides! How-to guides are a place where we walk you through implementing specific features of the Headless WordPress Toolkit. If you are looking to achieve a specific goal with the toolkit, you are in the right place. + +> [!note] Learn More +> For more info on how we layout our documentation and the the role played by How-to guides, please read about the [_Diátaxis_](https://diataxis.fr/how-to-guides/) approach we use. + +## Contributing + +If you feel like something is missing or you want to add documentation, we encourage you to contribute! Please check out our [Contributing Guide](https://github.com/wpengine/hwptoolkit/blob/main/CONTRIBUTING.md) for more details.