Freemius · evrpress · Jun 28, 2026 · Jun 28, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/.gitignore b/.gitignore
@@ -32,5 +32,13 @@ vendor/
 
 /vendor/
 
+# Screenshot captures (manifest and docs are committed)
+/screenshots/**
+!/screenshots/.gitkeep
+!/screenshots/README.md
+!/screenshots/image-manifest.json
+!/screenshots/image-manifest.schema.json
+
+
 # Cursor IDE config (local nested repo; not shared on origin)
 .cursor/
diff --git a/docs/README.md b/docs/README.md
@@ -1,91 +1,78 @@
 # Freemius for WordPress
 
-The Freemius for WordPress is a toolkit to help people sell products on their WordPress sites.
+If you are using WordPress with the Block Editor, the Freemius for WordPress plugin enables you to integrate the Freemius checkout directly and quickly while building landing/sales pages for your Freemius product. No JavaScript, theme hacking, or coding required!
 
-## General Idea
+![Block editor with Freemius checkout preview open](assets/docs-homepage-preview.png)
 
-This plugin helps you quickly set up a sales page for your WordPress product that you sell via Freemius.
+**Not using the Block Editor?**
 
-## How it works
+See how to use the [overlay checkout](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/) or the [hosted checkout](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-hosted-page/).
 
-The plugin uses the Freemius API to fetch the product data and display it in the block editor.
+Out of the box, Freemius for WordPress gives you:
 
-The plugin also allows you to add Freemius Checkout to any button of your WordPress content using the block editor.
+- **Native Block Editor support (Gutenberg):** Drop checkout buttons or pricing tables directly into your page layouts - just like adding any other block.
 
-## Requirements
+  _For example: Add a "Buy Now" button to your landing page in seconds._
 
-- WordPress 6.7+
-- Freemius account
-- Freemius product
+- **Dynamic pricing tables:** Display different plans with clear comparisons and calls-to-action.
 
-## Installation
+  _Example: Showcase "Starter / Pro / Agency" tiers side by side, with checkout built in._
 
-1. Install the plugin via the WordPress admin panel.
-2. Activate the plugin.
-3. Go to the Freemius settings page (Settings => Freemius) and enter your Freemius Token.
-4. Go to the "Editor Settings" page and enter `product_id`, `public_key`.
+- **Plan switching and trials:** Let customers upgrade, downgrade, or start with a free trial seamlessly.
 
-## Checkout Button
+  _Example: Offer a 14-day free trial that auto-converts to a paid plan without extra coding._
 
-The easiest way to enable a checkout button is to create a new page (or edit an existing one) and add a new button block to the content.
+- **Full compatibility with modern WordPress block themes and plugins:** Works out of the box with your existing WordPress block site setup - no theme hacks required.
 
+- **100% free and open source:** Transparent, community-driven, and extensible.
 
-https://github.com/user-attachments/assets/c07268f2-0dc1-439a-840c-7e52215016cb
+  _Example: Extend the plugin with your own block variations, or contribute improvements back to the repo._
 
+## Resources
 
-Enable the checkout for this button in the inspector panel.
+- [Download from WordPress.org.](https://wordpress.org/plugins/freemius/)
+- [GitHub repo.](https://github.com/Freemius/freemius-wp-plugin)
+- [Test now on Playground.](https://playground.wordpress.net/?plugin=freemius)
+- [Features, roadmap and the changelog.](https://github.com/Freemius/freemius-wp-plugin#readme)
 
-You can instantly preview the button by clicking the "Preview" button in the inspector panel. Change the properties for this specific button with the settings below.
+## How do I set up a Freemius checkout button?
 
-## Working with Scopes
+1. Download, install, and activate the plugin on your WordPress site.
+2. Add a button block to your page or post, then enable the Freemius checkout option in the button settings.
+3. Configure your product details, and the button will automatically handle the checkout process.
 
-The plugin allows you to create multiple scopes for your product. Each scope can have different pricing and checkout buttons.
+Here is a quick video demonstrating how to set up a Freemius checkout button:
 
-A scope can be enabled on these blocks (or their children):
+[How to set up a Freemius checkout button](https://www.youtube.com/watch?v=MTOuIBGan7E)
 
-- Group Block
-- Columns Block
-- Column Block
-- Button Block
+For step-by-step guides in this documentation, see [Getting started](getting-started.md).
 
-<img width="280" height="284" alt="enable_checkout_full" src="https://github.com/user-attachments/assets/52b2e108-f3f2-4fd2-8760-c730a8c48315" />
+## Documentation
 
+| Guide | What it covers |
+| ----- | -------------- |
+| [Getting started](getting-started.md) | Install the plugin, connect your Freemius product, add a checkout button, and build a pricing page |
+| [Freemius Button](button.md) | Enable checkout on a button, scopes, preview, and optional settings |
+| [Creating your Pricing page](creating-your-pricing-page.md) | Build a multi-plan pricing page with modifiers, scoped columns, mapped fields, and checkout buttons |
+| [Scopes](scopes.md) | Nested pricing contexts on one page (groups, columns, buttons) |
+| [Field mapping](mapping.md) | Pull plan price, title, description, and billing labels into blocks |
+| [Scope modifiers](modifiers.md) | Currency, billing cycle, and license toggles on the page |
+| [Settings](settings.md) | Admin tabs: Products, Editor Settings, and site-wide defaults |
 
+## FAQs
 
-Each scope inherits the properties of the parent scope. The first scope in the hierarchy will inherit the properties of the "Editor Settings" page.
+### Can I customize the checkout experience?
 
-### Mapping
+Yes, you can customize various aspects of the checkout process through the plugin settings, including product details, pricing, and the checkout flow.
 
-You can map certain fields from your plans (e.g., "title", "description", "price", etc.) to the content of the blocks.
+### How do I set up a Freemius checkout button?
 
-The following blocks can "receive" data from the scope:
+Add a **Button** block, turn on **Freemius Checkout** in the Freemius panel, and set your product under **Settings → Freemius**. See [Getting started](getting-started.md) and [Freemius Button](button.md).
 
-- Paragraph Block
-- HeadingBlock
-- Button Block
-
-Currently, 5 fields are supported:
-
-- Title
-- Description
-- Price
-- Licenses (1, 2, 3, Unlimited)
-- Billing Cycle (Monthly, Yearly, Lifetime)
-
-You can see a purple outline around all blocks with a scope. The dotted outline indicates a mapped field:
-
-<img width="1243" height="703" alt="pricing_with_scopes" src="https://github.com/user-attachments/assets/c84d5c2f-07c0-46df-8ac3-843f2961d493" />
-
-### Scope Modifiers
-
-Modifiers can be used to change the settings of the scope in which they are placed. They always change the scope of the next parent scope.
-
-The scope is enabled by adding the "Freemius Scope" block to the content.
-<img width="2439" height="609" alt="modifiers" src="https://github.com/user-attachments/assets/2f9441a1-4fa4-4285-a5e7-8e1f025dfe50" />
-
-You can click on the modifier directly in the editor to change the scope.
-
-https://github.com/user-attachments/assets/6a25e2cb-c169-4d2d-898c-d6a48f90e0c6
+### Is the plugin compatible with my theme?
 
+The plugin targets the Block Editor (Gutenberg). It works with block themes and classic themes that support the block editor.
 
+### Where is pricing data loaded from?
 
+Mapped prices and plan copy are saved when you edit and publish a page; the frontend does not call the Freemius API on every visit. After you change prices on the Freemius dashboard, reopen the page in the editor and **Update** it. See [Creating your Pricing page](creating-your-pricing-page.md#important-pricing-data-is-not-live-on-the-frontend).
diff --git a/docs/assets/button-key-settings.png b/docs/assets/button-key-settings.png
diff --git a/docs/assets/button-overview.png b/docs/assets/button-overview.png
diff --git a/docs/assets/button-track-callback.png b/docs/assets/button-track-callback.png
diff --git a/docs/assets/callback-editor.png b/docs/assets/callback-editor.png
diff --git a/docs/assets/checkout.png b/docs/assets/checkout.png
diff --git a/docs/assets/docs-homepage-preview.png b/docs/assets/docs-homepage-preview.png
diff --git a/docs/assets/key-settings.png b/docs/assets/key-settings.png
diff --git a/docs/assets/popout-editor.png b/docs/assets/popout-editor.png
diff --git a/docs/assets/preview.png b/docs/assets/preview.png
diff --git a/docs/assets/pricing-page-checkout-button.png b/docs/assets/pricing-page-checkout-button.png
diff --git a/docs/assets/pricing-page-modifiers-row.png b/docs/assets/pricing-page-modifiers-row.png
diff --git a/docs/assets/pricing-page-plan-column.png b/docs/assets/pricing-page-plan-column.png
diff --git a/docs/assets/pricing-page-playground.png b/docs/assets/pricing-page-playground.png
diff --git a/docs/assets/pricing-page-preview.png b/docs/assets/pricing-page-preview.png
diff --git a/docs/assets/scope-columns-overview.png b/docs/assets/scope-columns-overview.png
diff --git a/docs/assets/scope-enable-checkout.png b/docs/assets/scope-enable-checkout.png
diff --git a/docs/assets/scope-modifiers.png b/docs/assets/scope-modifiers.png
diff --git a/docs/assets/scope-pricing-mapped.png b/docs/assets/scope-pricing-mapped.png
diff --git a/docs/assets/scopes.png b/docs/assets/scopes.png
diff --git a/docs/assets/settings-editor.png b/docs/assets/settings-editor.png
diff --git a/docs/assets/settings-products.png b/docs/assets/settings-products.png
diff --git a/docs/button.md b/docs/button.md
@@ -1,95 +1,53 @@
 # Freemius Button
 
-The Freemius Button allows you to add Freemius Checkout to any button of your WordPress content using the block editor.
+The Freemius Button extends the core Button block with Freemius Checkout. When enabled, clicking the button opens the Freemius Checkout popup.
 
-## Overview
-
-The Freemius Button extends the core Button block with Freemius Checkout functionality. When enabled, clicking the button will open the Freemius Checkout popup to process payments.
-
-![Freemius Checkout](https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/checkout.png)
-
-## Getting Started
-
-1. Install the [Freemius for WordPress](https://wordpress.org/plugins/freemius/) plugin from the WordPress.org repository.
-2. Add a new button block to your content.
-3. Enable the Freemius Button by checking the "Freemius Checkout" checkbox.
-4. Configure the button settings as needed.
-
-## Configuration Scopes
+Use it **standalone** on any Button block — enable Freemius Checkout and configure checkout on the button itself. Or place it **inside a scope** (a Freemius-enabled Group, Column, or similar block) so it inherits product, plan, and modifiers from that scope.
 
-The button settings can be configured at three different scopes:
-
-1. **Global** - Settings that apply site-wide
-2. **Page** - Settings that apply to the current page/post
-3. **Button** - Settings specific to the individual button
+## Overview
 
-<img width="275" alt="scopes" src="https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/scopes.png" />
+![Mapped Freemius checkout button in the pricing table with Freemius sidebar settings highlighted](assets/button-overview.png)
 
-Settings cascade down from global to button level, with more specific scopes overriding broader ones. This means that if you set a setting at the global level, it will be applied to all buttons on your site. If you set a setting at the page level, it will be applied to all buttons on that page. If you set a setting at the button level, it will only be applied to that specific button.
+The example above shows a mapped checkout button inside a pricing table scope. See [Scopes](scopes.md) and [Mapping](mapping.md) for building similar layouts.
 
-This way, you can override the global settings for a specific page or button.
+For installation, your first checkout button, and testing with Preview, see [Getting started](getting-started.md).
 
-## Key Settings
+## Key settings
 
-- **Product ID** - Your Freemius product ID (required)
-- **Public Key** - Your Freemius public key (required)
-- **Plan ID** - Specific plan to offer
-- **Pricing ID** - Specific pricing to offer
-- **Billing Cycle** - Default billing cycle (monthly/annual)
-- **Currency** - Transaction currency
-- **Quantity** - Default quantity
-- **Coupon** - Default coupon code
-- **Custom Fields** - Additional checkout fields
-- **Success URL** - Redirect URL after successful purchase
-- **Cancel URL** - Redirect URL after cancellation
+- **Product ID** — Freemius product ID (required)
+- **Plan ID**, **Pricing ID**, **Billing Cycle**, **Currency**, **Quantity**, **Coupon**
+- **Success URL**, **Cancel URL**, **Custom Fields**
 
-Please refer to the [Freemius documentation](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/) for more information on these settings.
+See [Freemius checkout documentation](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/) for details.
 
-By default, settings that are not set are hidden. You can find them by clicking on the "three-dots-button" in the toolbar:
+Hidden settings are listed in the Freemius **options menu** (three dots on the Freemius panel header). Open it to show or hide fields such as Product ID and Plan:
 
-<img width="326" alt="key-settings" src="https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/key-settings.png" />
+![Freemius options menu with additional checkout field toggles](assets/button-key-settings.png)
 
 ## Customization
 
-The button appearance can be customized using the standard WordPress button block settings for:
-
-- Colors
-- Typography
-- Dimensions
-- Border
-- Spacing
+Use standard WordPress button block controls for colors, typography, dimensions, border, and spacing.
 
-## Events & Callbacks
+## Events and callbacks
 
-You can add custom JavaScript code to handle various checkout events:
+Handle checkout events with custom JavaScript:
 
-- `purchaseCompleted` - Called after a successful purchase
-- `success` - Called after a successful transaction
-- `cancel` - Called when checkout is canceled
-- `track` - Called for tracking events
+- `purchaseCompleted`, `success`, `cancel`, `track`
 
-To add custom JS, find the specific settings and enter the code you would like to execute when the event is triggered.
+Use **Track Callback** for advanced tracking across checkout events (currency changes, billing cycle updates, license count, and more). Open **Popout Editor** for a larger code editor:
 
-<img width="375" alt="popout-editor" src="https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/popout-editor.png" />
+![Track Callback in the Freemius button sidebar with Popout Editor open](assets/button-track-callback.png)
 
-You can also click on "**Popout Editor**" to get a bigger editor to enter your custom code.
-
-<img width="645" alt="callback-editor" src="https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/callback-editor.png" />
-
-Find examples on the [Freemius documentation](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/#tracking_purchases_with_google_analytics_and_facebook)
+For more `track` events, see the [Freemius checkout track documentation](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/#track).
 
 ## Preview
 
-<img width="375" alt="preview" src="https://raw.githubusercontent.com/Freemius/freemius-wp-plugin/refs/heads/main/docs/assets/preview.png"  />
-
-Use the Preview button in the toolbar or sidebar to test your checkout configuration before publishing.
+![Pricing page editor with checkout preview open and the Preview button outlined](assets/pricing-page-preview.png)
 
-The Auto Refresh option will automatically update the preview when settings change.
+Use **Preview** in the sidebar or toolbar to test checkout. **Auto Refresh** updates the preview when settings change.
 
 ## Tips
 
-- Configure common settings at the global scope
-- Override specific settings at page/button level as needed
-- Test the checkout flow using Preview mode
-- Use event callbacks to integrate with other functionality
-- Refer to [Freemius documentation](https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/) for detailed options
+- Inside a scope, the button inherits parent settings; override on the button only when needed
+- Test with Preview before publishing
+- Use callbacks to integrate analytics or custom flows