Merge pull request #516 from wpengine/hwp-previews-docs

docs(previews): Add how-to guides, tutorials and an explanation

Author: ahuseyn

docs/plugins/hwp-previews/explanation/core-concepts/index.md

@@ -3,4 +3,101 @@ title: "Core Concepts"
 description: "Deep dive explanations of the HWP Previews plugin's core concepts, architecture, and systems."
 ---
 
-@TODO
+## Overview
+
+This article provides an in-depth exploration of the fundamental concepts that power the HWP Previews plugin, covering the template-based URL system that enables framework-agnostic preview generation, the parameter registry that makes URLs dynamic and context-aware, the flexible post type configuration system, solutions for WordPress hierarchical content challenges, and the different preview modes available to content creators.
+
+## Core Architectural Concepts
+
+### 1. Preview URL Templates with Dynamic Parameters
+
+At the heart of HWP Previews is the concept of URL templates. Instead of hardcoding preview URLs, administrators define templates using placeholder tokens that get dynamically replaced with actual post data.
+
+For example, a template like:
+```
+https://mysite.com/preview?p={ID}&type={type}&status={status}
+```
+
+When previewing a draft post with ID 42 of type "page", this becomes:
+```
+https://mysite.com/preview?p=42&type=page&status=draft
+```
+
+This template approach ensures framework agnosticity, whether you're using Next.js with `/api/preview?slug={slug}`, a custom React app with `/preview/{ID}`, or any other front-end architecture. The system generates context-rich URLs that can pass any information your front-end needs to handle previews intelligently, from basic post data to complex hierarchical relationships.
+
+#### The Parameter Registry System
+
+HWP Previews maintains a parameter registry, a centralized collection of available dynamic parameters. Out of the box, it provides:
+
+- `{ID}` – Post ID
+- `{author_ID}` – Post author's user ID
+- `{status}` – Post status (draft, pending, etc.)
+- `{slug}` – Post slug
+- `{parent_ID}` – Parent post ID (for hierarchical types)
+- `{type}` – Post type slug
+- `{template}` – Template filename
+
+This registry is extensible through WordPress filters, allowing developers to add custom parameters (e.g., `{category}`, `{custom_field}`, or `{locale}` for multilingual sites).
+
+### 2. Post Type-Specific Configuration
+
+WordPress sites often have diverse content types (posts, pages, custom post types) each potentially requiring different preview handling. To address this challenge, HWP Previews provides per-post-type configuration.
+
+For each public post type, you can independently configure:
+- Whether previews are enabled at all
+- The preview URL template
+- Whether to display previews in an iframe within the editor
+- Whether to allow non-published posts as parents (for hierarchical types)
+
+### 3. Hierarchical Post Types and Parent Status
+
+WordPress supports hierarchical post types (like pages) where posts can have parent-child relationships. By default, WordPress only allows published posts to be parents. This creates a workflow problem: when building a site, you often want to establish page hierarchies while everything is still in draft.
+
+HWP Previews solves this with the "Allow All Statuses as Parent" option. When enabled for a post type, draft, pending, or private posts can serve as parents.
+
+### 4. Iframe vs. New Tab Preview Modes
+
+HWP Previews offers two preview rendering modes, each suited to different workflows:
+
+#### Iframe Mode
+When enabled, previews load directly within the WordPress editor in a sandboxed `<iframe>`. This provides an integrated experience, so you can see your changes alongside the preview, similar to the WordPress theme customizer.
+
+#### New Tab Mode
+When disabled, clicking "Preview" opens the preview URL in a new browser tab.
+
+### 5. Faust Integration
+
+When Faust.js is detected, HWP Previews automatically configures itself to work seamlessly with Faust's preview system. This provides Faust users with an upgrade path that maintains their existing workflows while gaining access to additional features like iframe mode, custom parameters, and per-post-type control.
+
+The integration removes potential conflicts by disabling Faust's native preview handling and pre-configuring preview URLs to match Faust's expected structure. This **compatibility without compromise** approach minimizes adoption barriers for users with existing Faust investments.
+
+## The Hook System and Extensibility
+
+HWP Previews provides a comprehensive system of WordPress actions and filters for extending functionality.
+
+### Key Extension Points
+
+`hwp_previews_register_parameters`: Add custom dynamic parameters
+`hwp_previews_filter_available_post_types`: Control which post types appear in settings
+`hwp_previews_filter_available_post_statuses`: Modify available post statuses
+`hwp_previews_template_path`: Replace the iframe preview template
+
+## Security Considerations
+
+While HWP Previews focuses on preview URL generation rather than authentication, its design acknowledges security concerns:
+
+1. **No token generation**: The plugin intentionally doesn't handle authentication tokens, that's the front-end's responsibility
+2. **URL encoding**: All parameter values are properly encoded to prevent injection attacks
+3. **Capability checks**: Admin settings pages require appropriate WordPress capabilities
+4. **Nonce verification**: AJAX requests (like dismissing notices) include nonce verification
+
+## Performance Characteristics
+
+HWP Previews is designed for minimal performance impact:
+
+- **Settings caching**: Configuration is cached and only loaded when needed
+- **Lazy initialization**: Services instantiate only when actually used
+- **Selective hooks**: Post-type-specific hooks only register for enabled post types
+- **No frontend overhead**: The plugin only activates for authenticated users in admin/preview contexts
+
+These choices reflect an understanding that preview functionality should never degrade the public site's performance.

docs/plugins/hwp-previews/how-to/configure-previews/hwp-previews-iframe.png

@@ -3,4 +3,114 @@ title: "Configure Previews"
 description: "Learn how to configure preview functionality using the HWP Previews plugin in your headless WordPress application."
 ---
 
-@TODO
+## Overview
+
+This guide shows you how to configure preview URLs for your headless WordPress site using HWP Previews. You'll set up preview links that redirect from WordPress to your front-end application with the necessary context data.
+
+> [!TIP]
+> Want to see HWP Previews in action first? Check out the working examples in the `examples/` directory that demonstrate integration with WP GraphQL and REST API. You can run them locally using `wp-env` to test the plugin functionality before configuring your own setup.
+
+## Prerequisites
+
+- HWP Previews plugin installed and activated
+- A running front-end application with a preview endpoint
+
+## 1. Access the settings page
+
+1. Log into your WordPress admin dashboard
+2. Navigate to **Settings > HWP Previews**
+
+![HWP Previews menu item in WordPress admin sidebar under Settings](hwp-previews-menu-item.png)
+
+You'll see tabs for each public post type on your site (Posts, Pages, and any custom post types).
+
+## 2. Configure a post type
+
+### a. Enable previews for the post type
+
+1. Click on the tab for the post type you want to configure (e.g., "Posts")
+2. Check the "Enable HWP Previews" box
+
+> [!NOTE]  
+> If you have Faust.js installed, this option will be enabled by default for all post types.
+
+### b. Set the preview URL template
+
+In the "Preview URL Template" field, enter your front-end preview endpoint URL with dynamic parameters:
+
+```
+https://mysite.com/api/preview?id={ID}&type={type}&status={status}
+```
+
+Available parameters:
+
+- `{ID}` - Post ID
+- `{author_ID}` - Post author's user ID
+- `{status}` - Post status (draft, pending, etc.)
+- `{slug}` - Post slug
+- `{parent_ID}` - Parent post ID (for hierarchical types)
+- `{type}` - Post type slug
+- `{template}` - Template filename
+
+The parameters sidebar shows descriptions for each available parameter.
+
+![HWP Previews post settings page showing the Posts tab with Enable HWP Previews checkbox, Preview URL Template field with example URL, and parameters sidebar](hwp-previews-post-settings.png)
+
+### c. Choose the preview mode
+
+Select how you want previews to display:
+
+- **Iframe mode**: Check "Load Previews in Iframe" to display previews within the WordPress editor
+- **New tab mode**: Leave unchecked to open previews in a new browser tab
+
+For iframe mode to work, your front-end must not set restrictive `X-Frame-Options` headers.
+
+### d. Optional: Configure hierarchical post types (Pages only)
+
+For hierarchical post types like Pages, you can allow draft posts to be parents by checking "Allow All Statuses as Parent" and saving changes, which lets you build page hierarchies before publishing content.
+
+![HWP Previews page settings showing the Pages tab with Enable HWP Previews checkbox, Preview URL Template field, and Allow All Statuses as Parent checkbox for hierarchical post types](hwp-previews-page-settings.png)
+
+## 3. Save your settings
+
+Click the "Save Changes" button at the bottom of the page.
+
+## 4. Test the preview
+
+1. Open any post of the configured type in the editor
+2. Make a change to the content
+3. Click the "Preview" button
+
+If configured correctly:
+- **Iframe mode**: The preview loads within the editor
+- **New tab mode**: A new tab opens with your front-end preview URL
+
+The URL will include the dynamic parameters you specified, for example:
+```
+https://mysite.com/api/preview?id=42&type=post&status=draft
+```
+
+![HWP Previews iframe mode showing a preview of a post loaded within the WordPress editor interface](hwp-previews-iframe.png)
+
+## Troubleshooting common issues
+
+### Preview button doesn't redirect
+
+Check that:
+- The "Enable HWP Previews" checkbox is checked for that post type
+- You've saved your settings
+- The Preview URL Template field is not empty
+
+### Iframe preview shows a blank screen
+
+Your front-end may be blocking iframe embedding. Either:
+- Make sure your front-end can properly handle authentication to show draft content
+- Configure your front-end to allow embedding from your WordPress domain
+- Switch to new tab mode by unchecking "Load Previews in Iframe"
+
+### Dynamic parameters show "PARAMETER_NOT_FOUND"
+
+This happens when you use a parameter that doesn't exist. Verify:
+- Parameter names are spelled correctly
+- Parameters are wrapped in curly braces: `{ID}` not `ID`
+- The parameter is available (check the parameters sidebar)

docs/plugins/hwp-previews/how-to/configure-previews/hwp-previews-menu-item.png

@@ -3,4 +3,56 @@ title: "Integrate with Faust.js"
 description: "Learn how to integrate the HWP Previews plugin with Faust.js in your headless WordPress application."
 ---
 
-@TODO
+## Overview
+
+This guide shows you how to use HWP Previews with Faust.js. The integration happens automatically when both plugins are installed.
+
+## Prerequisites
+
+- [Faust.js](https://wordpress.org/plugins/faustwp/) plugin installed and activated
+
+## 1. Install HWP Previews
+
+1. Install and activate the HWP Previews plugin
+2. Navigate to **Settings > HWP Previews**
+
+HWP Previews automatically detects Faust.js and configures itself to work with Faust's preview system.
+
+### Automatic setup
+
+When HWP Previews detects Faust.js, it:
+
+1. Enables previews for all public post types
+2. Sets the preview URL template to match Faust's expected format:
+   ```
+   {FAUST_FRONTEND_URI}/preview?p={ID}&preview=true&previewPathname=p{ID}&typeName={type}
+   ```
+3. Removes Faust.js's native preview link filter to prevent conflicts
+4. Disables Faust's redirect functionality for preview URLs
+5. Shows an admin notice on the settings page confirming the integration
+
+The `{FAUST_FRONTEND_URI}` is automatically pulled from your Faust.js settings. If not configured, it defaults to `http://localhost:3000`.
+
+### Authentication
+HWP Previews handles preview URL generation, but authentication remains the responsibility of your Faust front-end application. Continue using [Faust.js authentication](https://faustjs.org/docs/how-to/authentication/) to access draft content in previews.
+
+## 2. Verify the integration
+
+1. Go to **Settings > HWP Previews**
+2. Check any post type tab (Posts, Pages, etc.)
+3. Verify that:
+   - "Enable HWP Previews" is checked
+   - The Preview URL Template contains your Faust front-end URL
+
+![HWP Previews settings page showing automatic Faust.js integration with enabled previews and configured preview URL template](hwp-previews-faust-integration.png)
+
+## 3. Test previews
+
+1. Open any post in the WordPress editor
+2. Click the "Preview" button
+3. You should be redirected to your Faust front-end preview endpoint
+
+The preview URL will look like:
+```
+https://your-faust-site.com/preview?p=42&preview=true&previewPathname=p42&typeName=post
+```