From 9fbdbb60a4acf7573e4c20ea8a95bd937ae37483 Mon Sep 17 00:00:00 2001
From: ahuseyn <huseyn.aghayev@wpengine.com>
Date: Thu, 27 Nov 2025 13:43:20 +0100
Subject: [PATCH 1/4] update readme.txt and README.md

---
 plugins/hwp-previews/README.md  | 128 +++++---------------------------
 plugins/hwp-previews/readme.txt |  95 +++++++++++++++++++++++-
 2 files changed, 110 insertions(+), 113 deletions(-)

diff --git a/plugins/hwp-previews/README.md b/plugins/hwp-previews/README.md
index c70113e5..f83f55b5 100644
--- a/plugins/hwp-previews/README.md
+++ b/plugins/hwp-previews/README.md
@@ -3,7 +3,7 @@
 **Headless Previews** solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic.
 
 * [Join the Headless WordPress community on Discord.](https://discord.gg/headless-wordpress-836253505944813629)
-* [Documentation](#getting-started)
+* [Documentation](../../docs/plugins/hwp-previews/)
 
 
 -----
@@ -25,17 +25,6 @@
 
 -----
 
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Getting Started](#getting-started)
-- [Configuration](#configuration)
-- [Front-End Integration](#front-end-integration)
-- [Using With Faust.js](#using-with-faustjs)
-- [Extending the Functionality](#extending-the-functionality)
-- [Testing](#testing)
-
 ## Overview
 
 HWP Previews is a robust and extensible WordPress plugin that centralizes all preview configurations into a user-friendly settings interface.
@@ -56,116 +45,34 @@ This fundamental architectural shift creates what we call the "preview problem"
 - **Faust Compatibility**: The plugin is compatible with [Faust.js](https://faustjs.org/) and the [FaustWP plugin](https://github.com/wpengine/faustjs/tree/canary/plugins/faustwp).
 
 
->[!IMPORTANT]
+>[!NOTE]
 > For Faust users, HWP Previews integrates seamlessly, automatically configuring settings to match Faust's preview system. This allows you to maintain your existing preview workflow without additional setup.
 
-## Getting Started
-
-This guide will help you set up your first headless preview link for the "Posts" post type.
-
-1.  **Activate the Plugin:** Ensure "HWP Previews" is installed and activated.
-2.  **Navigate to Settings:** Go to **Settings > HWP Previews** in your WordPress admin dashboard.
-3.  **Enable for Posts:** On the "Posts" tab, check the "Enable HWP Previews" box. If you have Faust installed, this option will be enabled by default. Find more information about Faust integration below.
-4.  **Set the Preview URL:** In the "Preview URL Template" field for Posts, enter the URL for your front-end application's preview endpoint. Use parameters to add dynamic information that you want to access.
-5.  **Save and Test:** Save changes, go to any post, make a change, and click the "Preview" button. You should be redirected to the URL you just configured.
-
----
-
-## Project Structure
-
-```text
-hwp-previews/
-├── src/                        # Main plugin source code
-│   ├── Admin/                  # Admin settings, menu, and settings page logic
-│   ├── Hooks/                  # WordPress hooks and filters
-│   ├── Integration/            # Integrations (e.g. Faust)
-│   ├── Preview/                # Preview URL logic, template resolver, helpers
-│   ├── Plugin.php              # Main plugin class (entry point)
-│   └── Autoload.php            # PSR-4 autoloader
-├── examples/                   # Example front-end integrations for WP GraphQL and REST
-├── tests/                      # All test suites
-│   ├── wpunit/                 # WPBrowser/Codeception unit
-├── hwp-previews.php
-├── activation.php
-├── composer.json
-├── deactivation.php
-├── ACTIONS_AND_FILTERS.md
-├── TESTING.md
-├── README.md
-```
-
-## Configuration
-
-HWP Previews configuration located at **Settings > HWP Previews** page in your WP Admin. The settings are organized by post type.
-
-### Settings
-
-For each public post type, you can configure:
-
-- **Enable HWP Previews:** This is the master switch for the post type. If disabled, WordPress will revert to its default preview behavior for these posts.
-- **Allow All Statuses as Parent:** This option is only available for hierarchical post types like Pages. By default, WordPress only allows published posts to be parents. Enable this to build parent-child relationships using draft or pending posts.
-- **Load Previews in Iframe:** When enabled, the preview will be displayed directly within the WordPress editor in a sandboxed `<iframe>`. This provides a more integrated experience but requires your front-end to be configured to allow embedding. If disabled, clicking "Preview" will open a new browser tab.
-- **Preview URL:** You will be redirected to this link whenever you click the preview button for the enabled post type.
-
-> [!NOTE]  
-> Retrieval of settings is cached for performance.
-
-### Parameters
+## Requirements
 
-You can use the parameters on the sidebar to add dynamic context info to your preview URL. This information can be used by your front-end application to better handle the preview requests.
+- WordPress 6.0+
+- PHP 7.4+
 
-Currently below parameters are available by default, but you can add your own parameters by extending the plugin via hooks. Check Extending the Functionality section for details.
+## Installation
 
-- `{ID}` – Post ID
-- `{author_ID}` – Post author’s user ID
-- `{status}` – Post status slug
-- `{slug}` – Post slug
-- `{parent_ID}` – Parent post ID (hierarchical types)
-- `{type}` – Post type slug
-- `{template}` – Template filename
+### Option 1: Plugin Zip
 
-### Default Post Statuses Config:
+You can get the latest release here - <https://github.com/wpengine/hwptoolkit/releases/latest/download/hwp-previews.zip>
 
-Default post statuses are `publish`, `future`, `draft`, `pending`, `private`, `auto-draft` but these also modifiable via core hook.
+You can also download it from our release page - <https://github.com/wpengine/hwptoolkit/releases>
 
----
+### Option 2: Composer
 
-## Front-End Integration
+To install, you need to follow our guide here to install the plugin via composer - <https://github.com/wpengine/hwptoolkit/blob/main/docs/how-to/install-toolkit-plugins/index.md>
 
-HWP Previews is framework and API agnostic, meaning you can integrate it with any front-end application and with any data-fetching method (WPGraphQL, REST).
+Once you have the composer repository setup, please run `composer req wpengine/hwp-previews:*` to install the plugin.
 
-To get started quickly you can use our [example based on Next.js and WPGraphQL](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews/examples/hwp-preview-wpgraphql). This example uses the Draft Mode feature of Next.js.
+## Documentation
 
-For REST users, you can follow our example [here](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews/examples/hwp-preview-rest) with Next.js App Router.
+For detailed usage instructions, developer references, and examples, visit our comprehensive documentation:
 
-To implement your own approach from scratch you can refer to the appropriate documentation pages for each framework. HWP Previews relies on custom preview URLs, allowing you to integrate any method. Below you can find the guides to implement framework-specific preview mode.
-
-- [Next.js Draft Mode with Pages Router](https://nextjs.org/docs/pages/guides/draft-mode)
-- [Next.js Draft Mode with App router](https://nextjs.org/docs/app/guides/draft-mode)
-- [Nuxt usePreviewMode](https://nuxt.com/docs/api/composables/use-preview-mode)
-
----
-
-## Using With Faust.js
-
-This plugin is fully compatible with [Faust.js](https://faustjs.org/). It gives you the option to override Faust’s native preview system, providing granular control over preview URLs for use with any front-end framework.
-
-### Automatic Integration
-
-HWP Previews automatically detects when the Faust.js plugin is active to ensure a seamless integration. Upon detection, it pre-configures the following settings for all public post types:
-
-- The "Enable HWP Previews" toggle is activated by default.
-- The Preview URL is automatically updated to match Faust’s standard structure.
-
-This out-of-the-box configuration allows your existing preview workflow to continue functioning, without manual setup. You can continue to use [Faust.js authentication](https://faustjs.org/docs/how-to/authentication/) to access the preview pages.
-
----
-
-## Actions & Filters
-
-See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
-
----
+- [Documentation](../../docs/plugins/hwp-previews/index.md)
+- [Examples](./examples/)
 
 ## Testing
 
@@ -194,3 +101,6 @@ See [Testing.md](TESTING.md) for details on how to test the plugin.
 ![App Password](./screenshots/app_password.png)
 *App password setup for authentication.*
 </details>
+
+## License
+WP GPL 2
\ No newline at end of file
diff --git a/plugins/hwp-previews/readme.txt b/plugins/hwp-previews/readme.txt
index 47eba6cd..6fbc31b3 100644
--- a/plugins/hwp-previews/readme.txt
+++ b/plugins/hwp-previews/readme.txt
@@ -1,5 +1,5 @@
 === HWP Previews ===
-Contributors: wpengine
+Contributors: colin-murphy, joefusco, thdespou, ahuseyn, wpengine
 Tags: GraphQL, Headless, Previews, WPGraphQL, React, Rest
 Requires at least: 6.0
 Tested up to: 6.8.1
@@ -8,11 +8,98 @@ Stable tag: 0.0.13
 License: GPL-2.0
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 
+Headless Previews solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic.
+
 == Description ==
 
-A headless WordPress plugin for Previews.
+**HWP Previews** is a robust and extensible WordPress plugin that centralizes all preview configurations into a user-friendly settings interface. It enables seamless preview functionality for headless WordPress applications, allowing content creators to preview their changes in the frontend application before publishing.
+
+In traditional WordPress, previewing content is straightforward: clicking the "Preview" button shows you a draft version of your post on the same WordPress site. However, in headless WordPress architectures, where the front-end is decoupled from WordPress, this simple mechanism breaks down. HWP Previews bridges this gap, providing a centralized, framework-agnostic solution to preview management.
+
+= Key Features =
+
+**Framework Agnostic**
+* Works with any front-end framework (Next.js, Nuxt, React, Vue, etc.)
+* Supports any data-fetching method (WPGraphQL, REST API, or custom endpoints)
+* No vendor lock-in
+
+**Per Post Type Configuration**
+* Enable or disable previews for each public post type independently
+* Define custom URL templates with dynamic parameters
+* Choose between iframe or new tab preview modes
+* Allow draft posts as parents for hierarchical types
+
+**Dynamic URL Templates**
+* Use placeholder tokens to build context-rich preview URLs
+* Available tokens: `{ID}`, `{author_ID}`, `{status}`, `{slug}`, `{parent_ID}`, `{type}`, `{template}`
+* Build flexible preview URLs that pass exactly the data your front-end needs
+
+**Extensible Architecture**
+* Extend through WordPress hooks and filters
+* Add custom parameters and modify settings
+* Integrate with other plugins seamlessly
+
+**Faust.js Integration**
+* Automatic integration with Faust.js that pre-configures preview URLs
+* Removes conflicts while maintaining existing workflows
+* Works alongside FaustWP plugin
+
+= Use Cases =
+
+* **Headless CMS**: Preview content in your decoupled front-end before publishing
+* **Multi-site Management**: Configure different preview URLs for different post types
+* **Custom Post Types**: Set up previews for any custom post type
+* **Development Workflow**: Test content changes in staging environments
+* **Client Presentations**: Show draft content to clients before going live
+
+= Requirements =
+
+* WordPress 6.0 or higher
+* PHP 7.4 or higher
+
+= Documentation =
+
+For detailed documentation, guides, and examples, visit the [GitHub repository](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews).
+
+== Installation ==
+
+1. Upload the plugin files to `/wp-content/plugins/hwp-previews/`, or install the plugin through the WordPress plugins screen directly
+2. Activate the plugin through the 'Plugins' screen in WordPress
+3. Navigate to Settings -> HWP Previews in the WordPress admin to configure settings
+4. Enable previews for your desired post types and set preview URL templates
 
-== Upgrade Notice ==
 == Frequently Asked Questions ==
-== Screenshots ==
+
+= Is this plugin production-ready? =
+
+Yes. We recommend thorough testing on a local or staging before deploying to production.
+
+= Does this work with my front-end framework? =
+
+Yes! HWP Previews is framework-agnostic and works with Next.js, Nuxt, React, Vue, or any other front-end framework. You just need to set up a preview endpoint in your application.
+
+= Can I use this with WPGraphQL? =
+
+Absolutely! The plugin works with both WPGraphQL and REST API, or any custom data-fetching method you prefer.
+
+= Does this work with Faust.js? =
+
+Yes, HWP Previews automatically integrates with Faust.js and pre-configures settings to match Faust's preview system.
+
+= How do I set up the preview URL? =
+
+Go to Settings -> HWP Previews, select the post type tab, enable previews, and enter your front-end preview endpoint URL using dynamic parameters like `{ID}` and `{slug}`.
+
+= Can I customize the preview behavior? =
+
+Yes, the plugin provides extensive hooks and filters to customize preview behavior, add custom parameters, and integrate with other systems.
+
+= Where can I find documentation? =
+
+For detailed usage instructions, developer references, and examples, please visit the [Documentation](https://github.com/wpengine/hwptoolkit/blob/main/docs/plugins/hwp-previews/index.md) on GitHub.
+
+== Support ==
+
+For support, feature requests, or bug reports, please visit our [GitHub issues page](https://github.com/wpengine/hwptoolkit/issues).
+
 == Changelog ==

From e6060f7818cbf3abdd7a95d6f0e0defd71985d85 Mon Sep 17 00:00:00 2001
From: ahuseyn <huseyn.aghayev@wpengine.com>
Date: Fri, 28 Nov 2025 15:35:29 +0100
Subject: [PATCH 2/4] add initial major release changeset

---
 .changeset/short-ants-wave.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/short-ants-wave.md

diff --git a/.changeset/short-ants-wave.md b/.changeset/short-ants-wave.md
new file mode 100644
index 00000000..bef48ab0
--- /dev/null
+++ b/.changeset/short-ants-wave.md
@@ -0,0 +1,5 @@
+---
+"@wpengine/hwp-previews-wordpress-plugin": major
+---
+
+chore: Initial release of the HWP Previews Plugin

From aa4465d9b4286739a41d792840c3e639dd416742 Mon Sep 17 00:00:00 2001
From: ahuseyn <huseyn.aghayev@wpengine.com>
Date: Mon, 1 Dec 2025 13:16:43 +0100
Subject: [PATCH 3/4] automation test

---
 plugins/hwp-previews/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/hwp-previews/README.md b/plugins/hwp-previews/README.md
index ccc00059..592281b5 100644
--- a/plugins/hwp-previews/README.md
+++ b/plugins/hwp-previews/README.md
@@ -16,6 +16,7 @@
 [![Code Coverage](https://img.shields.io/badge/coverage-%3E95%25-brightgreen?label=Code%20Coverage)](https://github.com/wpengine/hwptoolkit/actions)
 [![Code Quality](https://github.com/wpengine/hwptoolkit/actions/workflows/code-quality.yml/badge.svg)](https://github.com/wpengine/hwptoolkit/actions/workflows/code-quality.yml)
 [![End-to-End Tests](https://github.com/wpengine/hwptoolkit/actions/workflows/e2e-test.yml/badge.svg)](https://github.com/wpengine/hwptoolkit/actions/workflows/e2e-test.yml)
+
 -----
 
 

From 9d6568990a4ecbdc4d98329f890f78c0fc505a18 Mon Sep 17 00:00:00 2001
From: ahuseyn <huseyn.aghayev@wpengine.com>
Date: Mon, 1 Dec 2025 13:18:04 +0100
Subject: [PATCH 4/4] automation test 2

---
 plugins/hwp-previews/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/hwp-previews/README.md b/plugins/hwp-previews/README.md
index 592281b5..cfa7c64d 100644
--- a/plugins/hwp-previews/README.md
+++ b/plugins/hwp-previews/README.md
@@ -17,6 +17,7 @@
 [![Code Quality](https://github.com/wpengine/hwptoolkit/actions/workflows/code-quality.yml/badge.svg)](https://github.com/wpengine/hwptoolkit/actions/workflows/code-quality.yml)
 [![End-to-End Tests](https://github.com/wpengine/hwptoolkit/actions/workflows/e2e-test.yml/badge.svg)](https://github.com/wpengine/hwptoolkit/actions/workflows/e2e-test.yml)
 
+
 -----