Merge pull request #480 from wpengine/chore-move-and-validate-logging-docs

chore:  Move and rewrite WPGraphQL Logging Docs

Author: colinmurphy

.remarkrc.json

@@ -0,0 +1,10 @@
+{
+    "plugins": [
+      "remark-frontmatter",
+      "remark-gfm",
+      "remark-preset-lint-recommended"
+    ],
+    "settings": {
+      "linkReference": false
+    }
+}

docs/README.md

@@ -1,16 +1,27 @@
-# HWP Toolkit Documentation
+---
+title: "Documentation"
+description: "Documentation for the Headless WordPress Toolkit, a modern, framework-agnostic collection of plugins and packages for building headless WordPress applications."
+---
+
+
+## WPGraphQL Logging Plugin
+
+| Title                              | Description                  |
+|------------------------------------|------------------------------|
+| [WPGraphQL Logging Plugin](plugins/wpgraphql-logging/) | Logging for WPGraphQL requests with granular lifecycle events and Monolog integration. |
+
 
 
 ## Explanation Documentation
 
 | Title                              | Description                  |
 |------------------------------------|------------------------------|
-| [GET vs POST](explanation/get-vs-post.md) | Explanation on choosing between GET and POST methods for WPGraphQL requests. |
-| [GraphQL Endpoints](explanation/graphql-endpoints.md) | Documentation on differences between using /graphql or ?graphql for WPGraphQL endpoint. |
-| [Headless Authentication](explanation/headless-authentication.md) | Overview of user authentication and access control in a decoupled WordPress architecture. |
-| [Rendering Options](explanation/rendering-options.md) | A document that explores the various approaches to rendering content from a headless WordPress installation. |
-| [Routing](explanation/routing.md)   | A comprehensive explanation on routing in a headless WordPress application.      |
-| [Sitemaps](explanation/sitemaps.md) | A comprehensive explanation on sitemaps in a headless WordPress application.     |
+| [GET vs POST](explanation/get-vs-post/index.md) | Explanation on choosing between GET and POST methods for WPGraphQL requests. |
+| [GraphQL Endpoints](explanation/graphql-endpoints/index.md) | Documentation on differences between using /graphql or ?graphql for WPGraphQL endpoint. |
+| [Headless Authentication](explanation/headless-authentication/index.md) | Overview of user authentication and access control in a decoupled WordPress architecture. |
+| [Rendering Options](explanation/rendering-options/index.md) | A document that explores the various approaches to rendering content from a headless WordPress installation. |
+| [Routing](explanation/routing/index.md)   | A comprehensive explanation on routing in a headless WordPress application.      |
+| [Sitemaps](explanation/sitemaps/index.md) | A comprehensive explanation on sitemaps in a headless WordPress application.     |
 
 
 ## How To Documentation

docs/explanation/get-vs-post.md docs/explanation/get-vs-post/index.mddocs/explanation/get-vs-post.md renamed to docs/explanation/get-vs-post/index.md

@@ -3,7 +3,7 @@ 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
+## Overview
 
 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.
 
@@ -52,3 +52,7 @@ curl -X POST \
 
 # Summary
 While both methods have their uses, POST requests are generally recommended for WPGraphQL due to their flexibility, security advantages, and ability to handle complex queries. However, GET requests can be useful for simple, cacheable queries and is useful when paired with caching mechanisms like the Smart Cache plugin. Consider your specific use case, security requirements, and caching needs when choosing between the two methods.
+
+## 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.

docs/explanation/graphql-endpoints.md …s/explanation/graphql-endpoints/index.mddocs/explanation/graphql-endpoints.md renamed to docs/explanation/graphql-endpoints/index.md docs/explanation/graphql-endpoints.md renamed to docs/explanation/graphql-endpoints/index.md

@@ -42,4 +42,8 @@ add_filter( 'graphql_endpoint', 'my_new_graphql_endpoint' );
 ```
 This code would change the default `/graphql` endpoint to `/my_endpoint`.
 
-Alternatively, you can configure the endpoint directly in the **WPGraphQL Settings** under **GraphQL Endpoint**, without needing to modify your code. 
+Alternatively, you can configure the endpoint directly in the **WPGraphQL Settings** under **GraphQL Endpoint**, without needing to modify your code.
+
+## 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.

…s/explanation/headless-authentication.md …anation/headless-authentication/index.mddocs/explanation/headless-authentication.md renamed to docs/explanation/headless-authentication/index.md docs/explanation/headless-authentication.md renamed to docs/explanation/headless-authentication/index.md

@@ -104,4 +104,8 @@ To tie everything together, we will provide:
 Our approach to authentication in headless WordPress emphasizes **modularity**, **security**, and developer **experience**. To support these principles, we will provide **ready-to-use code snippets** and **example boilerplate code** that you can easily integrate into your application.
 
 ## Example use case
-For example, if you're building a headless WordPress application with a React frontend, you can use our code snippets to implement Credentials authentication. You can integrate our boilerplate code for handling access tokens securely, including token storage and refresh logic, without needing to install additional dependencies.
+For example, if you're building a headless WordPress application with a React frontend, you can use our code snippets to implement Credentials authentication. You can integrate our boilerplate code for handling access tokens securely, including token storage and refresh logic, without needing to install additional dependencies.
+
+## 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.

docs/explanation/rendering-options.md …s/explanation/rendering-options/index.mddocs/explanation/rendering-options.md renamed to docs/explanation/rendering-options/index.md docs/explanation/rendering-options.md renamed to docs/explanation/rendering-options/index.md

@@ -3,7 +3,6 @@ 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
 
 This document explores the various approaches to rendering content from a headless WordPress installation. As a front-end developer working with headless WordPress, you'll need to make important decisions about how to handle and display WordPress content in your frontend application. This guide aims to help you understand the available options, their trade-offs, and best practices.
@@ -142,3 +141,7 @@ Considerations
 * Styling Parity: Achieving perfect styling parity can be challenging due to the dynamic nature of WordPress styles.
 
 * Maintenance: Styles may change with theme updates, customizations or major WordPress updates, requiring periodic updates in your headless application.
+
+## 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.

docs/explanation/routing.md docs/explanation/routing/index.mddocs/explanation/routing.md renamed to docs/explanation/routing/index.md

@@ -469,3 +469,7 @@ In traditional WordPress, custom post types (CPTs) are registered using `registe
 
 - `/portfolio/` → Archive page for portfolio items
 - `/portfolio/project-name/` → Single portfolio item
+
+## 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.

docs/explanation/sitemaps.md docs/explanation/sitemaps/index.mddocs/explanation/sitemaps.md renamed to docs/explanation/sitemaps/index.md

@@ -3,7 +3,7 @@ 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
+## A Comprehensive Overview
 
 ## What is a Sitemap?
 A sitemap is an XML file that provides a structured list of pages on a website by helping search engines discover and crawl content more efficiently. It acts as a roadmap of your website's structure, containing important metadata about each page.
@@ -108,7 +108,7 @@ This route will serve the WordPress `sitemap.xml` in your Next.js application dy
 - **Cons**
     * Limited flexibility for custom frontend routes not defined in WordPress
     * Requires proper URL transformation to replace backend URLs with frontend URLs
-    * May require additional handling for caching and performance 
+    * May require additional handling for caching and performance
     * May propagate any errors experienced in WordPress when proxying the `sitemap.xml`
 
 2. **Generating a Sitemap from GraphQL Content**
@@ -133,13 +133,13 @@ export async function generateSitemap() {
     fetchAllPages(),
   ]);
   const allContent = [
-    ...data.posts.nodes.map(post => ({ 
-      slug: `posts/${post.slug}`, 
-      modified: post.modified 
+    ...data.posts.nodes.map(post => ({
+      slug: `posts/${post.slug}`,
+      modified: post.modified
     })),
-    ...data.pages.nodes.map(page => ({ 
-      slug: page.slug, 
-      modified: page.modified 
+    ...data.pages.nodes.map(page => ({
+      slug: page.slug,
+      modified: page.modified
     })),
     // Add custom frontend routes here
     { slug: '', modified: new Date().toISOString() }, // Homepage
@@ -159,17 +159,17 @@ export async function generateSitemap() {
 }
 export async function getServerSideProps({ res }) {
   const sitemap = await generateSitemap();
-  
+
   res.setHeader('Content-Type', 'application/xml');
   res.write(sitemap);
   res.end();
-  
+
   return { props: {} };
 }
 
 export async function GET() {
   const sitemap = await generateSitemap();
-  
+
   return new Response(sitemap, {
     headers: {
       'Content-Type': 'application/xml',
@@ -182,7 +182,7 @@ export async function GET() {
     * Ability to include custom frontend routes not defined in WordPress
     * Easy integration with Next.js data fetching methods
 
-- **Cons**: 
+- **Cons**:
     * More complex implementation than proxying
     * Requires manual updates to include new content types or custom routes
     * May require pagination handling for large sites
@@ -199,25 +199,25 @@ import { DOMParser } from 'xmldom';
 export async function GET() {
   const response = await fetch(`${process.env.WORDPRESS_URL}/wp-sitemap.xml`);
   const sitemapIndex = await response.text();
-  
+
   const parser = new DOMParser();
   const xmlDoc = parser.parseFromString(sitemapIndex, 'text/xml');
   const sitemapUrls = Array.from(xmlDoc.getElementsByTagName('loc')).map(
     node => node.textContent
   );
-  
+
   const processedSitemaps = await Promise.all(
     sitemapUrls.map(async (url) => {
       const sitemapResponse = await fetch(url);
       const sitemapContent = await sitemapResponse.text();
-      
+
       return sitemapContent.replace(
         new RegExp(process.env.WORDPRESS_URL, 'g'),
         process.env.FRONTEND_URL
       );
     })
   );
-  
+
   const frontendRoutesSitemap = `
     <?xml version="1.0" encoding="UTF-8"?>
     <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
@@ -228,7 +228,7 @@ export async function GET() {
       <!-- Add more custom routes as needed -->
     </urlset>
   `;
-  
+
   const combinedSitemap = `
     <?xml version="1.0" encoding="UTF-8"?>
     <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
@@ -242,7 +242,7 @@ export async function GET() {
       </sitemap>
     </sitemapindex>
   `;
-  
+
   return new Response(combinedSitemap, {
     headers: {
       'Content-Type': 'application/xml',
@@ -261,3 +261,7 @@ export async function GET() {
     * Most complex implementation of the three approaches.
     * Requires handling multiple sitemap files
     * May have performance implications if not properly cached
+
+## 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.

docs/explanation/sitemaps-1.png docs/explanation/sitemaps/sitemaps-1.pngdocs/explanation/sitemaps-1.png renamed to docs/explanation/sitemaps/sitemaps-1.png

@@ -3,7 +3,7 @@ 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
+## Overview
 
 You can install any HWP Toolkit plugin using Composer, which is the recommended way for modern WordPress development workflows.
 
@@ -15,6 +15,9 @@ You can also install them manually from our [Releases](https://github.com/wpengi
 - WordPress 6.0+
 - PHP 7.4+
 
+>[!NOTE]
+> WPGraphQL Logging Plugin requires PHP 8.1.2 in order to work.
+
 ### Available Plugins
 
 - [wpengine/hwp-previews](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews#readme)