Document the new Pro PDF Viewer widget

Adds the docs-site page and the website marketing copy for the PDF
Viewer widget shipped in Pro 20260908.1.

- docs: full widget guide (source, zoom, toolbar, styling, gotchas),
  listed in the Pro getting-started widget index, with the usual two
  placeholder screenshots to be replaced with real captures.
- getting-started: PDF Viewer noted as having no WooCommerce or ACF
  dependency.
- marketing: widget page plus a "What's included" entry and an updated
  strapline on the Pro overview.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env

@@ -3,7 +3,7 @@
 CONTAINER_NAME=docusaurus-docs
 
 # Port Docusaurus serves on inside the container.
-PORT=3000
+PORT=3080
 
 # Production URL of the docs site. Update this once you've picked the
 # subdomain, then run `docker compose up -d --build` to rebuild with it —

README.md

@@ -70,4 +70,4 @@ Edit `SITE_URL` in `.env`, then `docker compose up -d --build`. Docusaurus bakes
 
 A handful of "See Pro" / "See free plugin" cross-links inside the docs were written for the original plugin repo structure and were adjusted during setup — all internal links were checked and resolve correctly as of this build. If you reorganise the `docs/` folder structure later, re-check cross-plugin links (the free and pro plugin folders link to each other in a few places, e.g. product-attribute-colours ↔ the Pro widget that displays swatches).
 
-The marketing/"what it does" copy (as opposed to this how-to content) is intended for regular Elementor pages on dotjuice.co.uk, not this docs site — see each plugin's `documentation/marketing/` folder in its own repo.
+The marketing/"what it does" copy (as opposed to this how-to content) is intended for regular Elementor pages on dotjuice.co.uk, not this docs site — it lives in this repo under `marketing/<plugin>/`. The copies in each plugin repo's own `documentation/` folder are abandoned. Those pages pull the markdown straight from this repo's raw URLs via the free plugin's Markdown widget / `[dj_markdown]` shortcode, so a commit here updates the website copy.

docker-compose.yaml

@@ -10,17 +10,19 @@ services:
     restart: always
     environment:
       SITE_URL: ${SITE_URL}
-      NODE_ENV: production
+      NODE_ENV: development
     volumes:
-      # The markdown source content — edit files here, then
-      # `docker compose up -d --build` (or just `restart`) to rebuild and
-      # pick up the changes. Organised as one folder per plugin.
+      # The markdown source content — edit files in here and the running dev
+      # server picks them up automatically: no rebuild, no restart. Organised
+      # as one folder per plugin.
       - ./docs:/app/docs
-    # Rebuilds the static site fresh on every container start (picking up
-    # whatever is currently in ./docs and the current SITE_URL), then serves
-    # the result. A few seconds slower to start than pre-built static files,
-    # but means editing docs never requires touching the image.
-    command: sh -c "npm run build && npm run serve -- --host 0.0.0.0 --port ${PORT}"
+    # Runs the Docusaurus dev server, which watches ./docs and recompiles on
+    # every change, so editing a doc updates the live site with no container
+    # restart or rebuild. `--poll` makes file-change detection reliable across
+    # the bind mount. For a truly live browser refresh (HMR) enable
+    # "Websockets Support" on this host in Nginx Proxy Manager; without it an
+    # already-open tab still updates on the next manual refresh.
+    command: sh -c "npm run start -- --host 0.0.0.0 --port ${PORT} --no-open --poll 1000"
     networks:
       - proxy
     # No host port published — Nginx Proxy Manager reaches this container

docs/dotjuice-elementor-tools-pro/getting-started.md

@@ -4,9 +4,9 @@
 
 Dotjuice Elementor Tools Pro requires:
 
-- **The free [Dotjuice Elementor Tools](../../../dotjuice-elementor-tools/documentation/marketing/overview.md) plugin**, installed and active — Pro is an add-on, not a standalone plugin.
+- **The free [Dotjuice Elementor Tools](../dotjuice-elementor-tools/getting-started.md) plugin**, installed and active — Pro is an add-on, not a standalone plugin.
 - **Elementor** (required by the free plugin).
-- **WooCommerce**, for every WooCommerce-related widget (all of them except ACF Frontend Form).
+- **WooCommerce**, for every WooCommerce-related widget (all of them except ACF Frontend Form and PDF Viewer).
 - **Advanced Custom Fields (ACF)**, only for the ACF Frontend Form widget.
 - **Elementor Pro**, only for Woo Quick View's popup and the [EspoCRM Lead Capture](espocrm-integration.md) integration (Forms is an Elementor Pro feature).
 
@@ -24,6 +24,7 @@ If a specific widget is missing:
 
 - **All WooCommerce widgets** need WooCommerce active.
 - **ACF Frontend Form** needs Advanced Custom Fields active.
+- **PDF Viewer** has no plugin dependencies at all beyond your Pro licence.
 - **Woo Quick View** needs **Elementor Pro** for its popup functionality — without Elementor Pro, its button falls back to a plain link to the product page instead of opening a popup.
 
 ## Widget guides
@@ -32,8 +33,8 @@ If a specific widget is missing:
 - [Woo Cart](widgets/woo-cart.md)
 - [Woo Quick View](widgets/woo-quick-view.md)
 - [Woo Custom Product Tabs](widgets/woo-custom-product-tabs.md)
-- [Woo Add Product Tab](widgets/woo-add-product-tab.md)
 - [ACF Frontend Form](widgets/acf-frontend-form.md)
+- [PDF Viewer](widgets/pdf-viewer.md)
 
 ## Integrations
 

docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md

@@ -2,31 +2,74 @@
 
 Found in the Elementor panel under **Dotjuice → ACF Frontend form**. Requires Advanced Custom Fields (ACF).
 
+![The ACF Frontend Form widget controls in the Elementor panel](../assets/img/acf-frontend-form-controls.png)
+*Screenshot: the widget selected in the editor with the Form Settings section open, showing the Form Mode, New Post Type, and New Post Status controls.*
+
 ## How it works
 
-Place this widget on a template that renders a single post or page — it displays an editable form for **whichever post is currently being viewed**, using ACF's own native form rendering. This widget only works on singular posts/pages (a single product, a single post, a single custom post type entry); it doesn't render anything on archive pages, the homepage, or similar listing pages.
+This widget renders an editable form using ACF's own native form rendering (so tabs, repeaters, and every field type look and behave exactly as they do in the WordPress dashboard). It can work in one of two modes:
+
+![An ACF frontend form rendered on a live page](../assets/img/acf-frontend-form-frontend.png)
+*Screenshot: a front-end ACF form on a published page, showing field groups rendered with tabs and a Submit button.*
+- **Update current post** — edits **whichever post is being viewed**. Place it on a single-post/product/page template in the Elementor Theme Builder.
+- **Create new post** — creates a **brand-new post** of a type you choose. Place it on a normal page (e.g. a "Submit a Case Study" page).
+
+You pick the mode explicitly in the widget settings — see below.
 
 ## Content settings
 
 | Setting | What it does |
 |---|---|
+| **Form Mode** | **Update current post** edits the post/page being viewed (use in a single-post template). **Create new post** makes a new post of the type below (use on a normal page). |
+| **New Post Type** | *(Create mode only)* The post type the new entry is created as — any public post type on your site. |
+| **New Post Status** | *(Create mode only)* The status the new post is saved with: Draft, Pending Review, Published, or Private. Draft or Pending is recommended for public submission forms so you can review before it goes live. |
+| **Redirect After Submit** | Optional. Where to send the visitor after a successful submit — leave blank to stay on the page. You can use the tokens `%post_url%` (the created/edited post) and `%post_id%`. |
 | **ACF Field Groups** | Choose which of your site's ACF field groups should be editable in this form. Nothing renders until at least one is selected. |
 | **Enable Title** | Includes the post title as an editable field. |
 | **Enable Content** | Includes the main content editor as an editable field. |
-| **Submit Button Label** | The text on the form's submit button (default "Update"). |
+| **Submit Button Label** | The text on the form's submit button. |
+
+## Which mode should I use?
+
+Note that a normal WordPress **Page** counts as a "single" item, so the widget can't reliably guess your intent — that's why the mode is an explicit choice rather than automatic.
+
+- Building an **edit form** inside a Single Post / Single Product / Single CPT template? → **Update current post**.
+- Building a **submission form** on a standalone page (front-end post creation)? → **Create new post**, and set the post type + a Draft/Pending status.
+
+## Styling
+
+The style tab targets ACF's real markup, and the tabs render live in the Elementor editor so you can see your changes as you make them (see "Live editing" below).
+
+**ACF Tabs** — typography, tab padding, gap between tabs, tab border radius, a border around each tab button (handy for removing the white borders ACF outputs by default), an underline colour/width for the tab bar, and Normal / Hover / Active colour states (text + background) for the tab buttons.
+
+**Fields & Labels**
+- *Labels* — colour and typography.
+- *Field Separator* — colour and width of the top border ACF draws between stacked fields.
+- *Inputs* — border, radius and padding, plus **Normal** and **Active / Focus** states, each with their own text colour and background. The Focus state adds a border colour and an optional glow/outline ring so the active field stands out.
+
+**Submit Button** — typography, padding, radius, border, and Normal / Hover colours.
+
+Several of ACF's default structural borders and fills (the tab-bar border and background, the divider between side-by-side fields, and the box around taxonomy checkbox lists) are removed automatically to give a clean starting point.
+
+## Live editing
+
+The ACF tab bar is normally built by ACF's own JavaScript, which doesn't run inside the Elementor editor. This widget loads ACF's scripts into the editor preview and re-initialises the form when Elementor renders it, so the tabs appear as real tabs and your tab/field styling updates live. On first open there may be a brief flash of a plain list before it becomes tabs — that's normal and only happens in the editor.
 
 ## Setting it up
 
-1. Place the widget on a Single Post, Single Product, or other singular template in your Elementor Theme Builder.
-2. Select the ACF field group(s) you want editable.
-3. Decide whether the post title and/or content should be editable too.
-4. Publish and test by viewing an actual individual post/page that uses this template.
+1. Add the widget to the appropriate template or page.
+2. Set **Form Mode** — Update for an edit form in a single template, or Create for a submission form on a page (then choose the new post type and status).
+3. Select the ACF field group(s) you want in the form.
+4. Decide whether the post title and/or content should be editable too.
+5. Optionally set a redirect for after submit.
+6. Publish and test with a real submission.
 
 ## ⚠ Important: this widget has no built-in access restriction
 
-Anyone who can view the page this widget is placed on can submit changes through the form — there's no automatic login requirement or capability check. If you only want logged-in users, specific roles, or the post's author to be able to edit, you'll need to add that restriction yourself: placing the widget inside a members-only page, using a membership/restriction plugin, or a conditional visibility rule in Elementor Pro. Don't place this widget on a fully public page unless open editing is genuinely what you want.
+Anyone who can view the page this widget is placed on can submit the form — there's no automatic login requirement or capability check. This matters for **both** modes: on an Update form it means anyone could edit the post; on a Create form it means anyone could create posts. If you only want logged-in users, specific roles, or the post's author to use it, add that restriction yourself — a members-only page, a membership/restriction plugin, or an Elementor Pro conditional-visibility rule. Don't place this widget on a fully public page unless open editing/submission is genuinely what you want.
 
 ## Good to know
 
-- This widget only renders a form when viewing an actual singular post or page — on archives, the homepage, or search results, it won't display anything.
-- The uploader for image/file fields uses a simple file picker rather than the full WordPress media library browser.
+- Submissions are processed early (before the page renders), so saving and the after-submit redirect work reliably — including when the widget lives in a Theme Builder template.
+- In **Update** mode the widget only renders on an actual singular post/page; on archives, the homepage, or search results it won't display. **Create** mode works on any page.
+- Remotely fetched images/files use ACF's basic uploader (a simple file picker) rather than the full WordPress media library browser.

docs/dotjuice-elementor-tools-pro/widgets/pdf-viewer.md

@@ -0,0 +1,77 @@
+# PDF Viewer
+
+Found in the Elementor panel under **Dotjuice → PDF Viewer**. No WooCommerce or ACF dependency — it only needs an active Pro licence.
+
+Displays a PDF — from your media library or an external URL — as a self-contained viewer built into your page: one page at a time on a styleable canvas, with a toolbar for navigation, zoom, fullscreen, download and print.
+
+![The PDF Viewer widget settings in the Elementor panel](../assets/img/pdf-viewer-controls.png)
+*Screenshot: the widget selected in the editor with the PDF File section open, showing the Media Library / External URL source toggle and the Lazy Load switch.*
+
+## How it works
+
+The widget draws each page itself using PDF.js (a copy of which ships inside the plugin — nothing is loaded from a third-party CDN), rather than handing the file to the browser's built-in PDF plugin in an iframe. That matters because the native viewer looks completely different from browser to browser, can't be styled, and on some mobile browsers refuses to display inline at all. Here, every visitor sees the same viewer, and it inherits the colours, borders and spacing you set in Elementor.
+
+Only the page being viewed is fetched and decoded, so opening a 200-page brochure doesn't mean downloading and rendering all 200 pages up front. Pages are rendered at the visitor's device pixel ratio, so text stays sharp on retina and high-DPI screens.
+
+![The PDF Viewer on the front end](../assets/img/pdf-viewer-frontend.png)
+*Screenshot: a PDF displayed on a page, with the toolbar showing page navigation, zoom buttons, fullscreen, download and print.*
+
+## Content settings
+
+### PDF File
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Source** | Media Library | Media Library (pick or upload a PDF) or External URL (a PDF hosted elsewhere). |
+| **Upload PDF** / **PDF URL** | — | The file itself, depending on Source. |
+| **Download Filename** | Source filename | Suggested filename for the Download button. Browsers only honour this for files on your own domain — for a PDF on another domain the browser names the file itself. |
+| **Initial Page** | 1 | The page shown when the viewer first loads. A number past the end of the document is clamped to the last page. |
+| **Lazy Load** | On | Don't fetch or render the PDF until the widget scrolls into view (loading starts about 200px before it reaches the viewport). Turn it off for a viewer above the fold that you want ready immediately. Lazy loading is always disabled inside the Elementor editor, so the widget previews straight away while you're designing. |
+
+### Zoom
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Default Zoom** | Fit Width | **Fit Width** scales the page to the width of the viewing area, **Fit Page** scales it so the whole page fits within the area's height as well, and **Custom Percentage** uses a fixed zoom. |
+| **Zoom Level (%)** | 100 | The fixed zoom, used only when Default Zoom is Custom. |
+| **Minimum (%)** | 25 | Lower limit for the toolbar's zoom-out button. |
+| **Maximum (%)** | 400 | Upper limit for the toolbar's zoom-in button. |
+
+The Minimum and Maximum also cap the Fit modes, so a page that would need to shrink below your minimum to fit is drawn at the minimum instead and scrolls inside the viewing area.
+
+### Toolbar
+
+Turn the toolbar on or off, place it at the **Top** or **Bottom** of the viewer, and show or hide each of its parts independently:
+
+| Part | What it gives the visitor |
+|---|---|
+| **Page Navigation** | Previous/Next buttons plus a page-number box showing `3 / 24`. The arrows disable themselves on the first and last page, and the number box can be typed into to jump straight to a page. |
+| **Zoom Buttons** | Zoom in and out in 25% steps, between your Minimum and Maximum. |
+| **Fullscreen Button** | Expands the viewing area to fill the screen, on a dark background, and returns with Escape. |
+| **Download Button** | Downloads the original PDF file. |
+| **Print Button** | Prints the original PDF, not a picture of the page on screen — so print output is full quality rather than a screen-resolution raster. |
+
+## Setting it up
+
+1. Add the widget and choose your PDF. Media Library is simplest — it also gives the Download button a sensible filename automatically.
+2. Set the viewing area's **Height** under Style → Viewing Area. This is the fixed height the viewer occupies in your layout; if the page is taller than that at the current zoom, it scrolls within the area.
+3. Pick a **Default Zoom** to suit the document. Fit Width suits text documents such as manuals and price lists; Fit Page suits single-page, poster-style PDFs where the whole thing should be visible at once.
+4. Hide any toolbar buttons you don't want — for example, dropping Download and Print on a document you'd rather people read on the page.
+5. Style the toolbar, buttons, page indicator and the page's own border and shadow to match your site.
+
+## Styling
+
+**Toolbar** — background, padding, and border; button icon size with separate Normal and Hover icon colours; page indicator colour and typography.
+
+**Viewing Area** — height (responsive, in px or vh), background colour, padding, and a border and box shadow applied to the page itself, which is what gives the "sheet of paper on a desk" look.
+
+**Loading / Error Text** — the colour of the loading message, a separate colour for error messages, and typography for both.
+
+## Good to know
+
+- The viewer shows **one page at a time** with Previous/Next controls rather than a continuous scroll. That keeps the widget's height predictable inside an Elementor layout instead of growing with the length of the document.
+- **Once a visitor presses a zoom button, the viewer stays at that zoom.** The Fit modes re-fit the page when the browser is resized or a phone is rotated, but zooming manually is treated as taking control, so it won't be undone by a later resize. Reloading the page returns to your Default Zoom.
+- **External PDFs need to allow cross-origin access.** Because the widget fetches and renders the file itself rather than embedding it, a PDF on another domain will only load if that server sends an `Access-Control-Allow-Origin` header permitting your site. Most file hosts and CDNs do; some do not, and a Dropbox or Google Drive share link generally won't. If an external PDF shows "Sorry, this PDF could not be loaded", this is almost always why — the fix is to upload the file to your own media library instead. PDFs from your own site are never affected.
+- **Print on an external PDF may open a new tab instead of a print dialog.** Printing works by loading the original file invisibly and printing it; browsers block that for files on another domain, so the widget falls back to opening the PDF in a new tab for the visitor to print from there.
+- The status area shows **"Loading PDF…"** while the file downloads and **"Sorry, this PDF could not be loaded"** if it fails — the second one styled in its own error colour. In the editor, a widget with no file selected shows a dashed placeholder box rather than an empty space.
+- Very large PDFs still take a moment to open, because PDF.js reads the document's structure before it can draw page one. Lazy Load keeps that cost off your initial page load.

docs/dotjuice-elementor-tools-pro/widgets/woo-add-product-tab.md

@@ -1,27 +0,0 @@
-# Woo Add Product Tab
-
-Found in the Elementor panel under **Dotjuice → Woo Add Product Tab**. Requires WooCommerce.
-
-## How it works
-
-Place this widget on your Single Product template — it adds one additional tab to WooCommerce's existing native tabs (Description, Additional Information, Reviews), styled to match them automatically since it uses WooCommerce's own tab system.
-
-## Content settings
-
-| Setting | Default | What it does |
-|---|---|---|
-| **Tab Title** | "Additional Info" | The tab's label. |
-| **Tab Content** | — | Rich-text content shown inside the tab. |
-| **Tab Order** | 50 | Controls where this tab sits relative to WooCommerce's defaults (Description = 10, Additional Information = 20, Reviews = 30). The default of 50 places it after Reviews — lower numbers move it earlier in the tab order. |
-
-## Setting it up
-
-1. Add the widget to your Single Product Elementor Theme Builder template.
-2. Set your tab title and content.
-3. Adjust Tab Order if you want it positioned somewhere other than last.
-
-## Good to know
-
-- **If this widget is placed on a shared Single Product template** (which is the normal way to use Elementor Theme Builder — one template applying to every product), every product using that template shows the **identical** tab title and content. This widget doesn't support per-product dynamic content — if you need different tab content on different products, you'll need [ACF Frontend Form](acf-frontend-form.md) with a custom field, or a separate template per product.
-- Only one tab per widget instance — add a second instance of this widget if you need two extra tabs.
-- You won't see this tab live in the Elementor editor canvas — a placeholder note explains this; preview it by viewing an actual product page on the front end.

docs/dotjuice-elementor-tools-pro/widgets/woo-cart.md

@@ -2,10 +2,16 @@
 
 Found in the Elementor panel under **Dotjuice → Woo Cart**. Requires WooCommerce (does not require Elementor Pro).
 
+![The Woo Cart widget layout settings in the Elementor panel](../assets/img/woo-cart-controls.png)
+*Screenshot: the widget selected in the editor with the Layout section open, showing Desktop Layout, Totals Column Width, and the Show Coupon toggle.*
+
 ## How it works
 
 Place this widget on your Cart page template. It renders your shopper's current cart — items, coupon box, and totals — built independently of WooCommerce's default cart template, so it's fully restyled from the ground up.
 
+![The Woo Cart widget on the front end](../assets/img/woo-cart-frontend.png)
+*Screenshot: a live cart page showing the two-column layout with cart items on the left, quantity steppers, and the totals panel on the right.*
+
 ## Layout settings
 
 | Setting | Default | What it does |

docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md

@@ -2,11 +2,16 @@
 
 Found in the Elementor panel under **Dotjuice → Woo Custom Product Tabs**. Requires WooCommerce.
 
+![The Woo Custom Product Tabs widget controls in the Elementor panel](../assets/img/woo-custom-product-tabs-controls.png)
+*Screenshot: the widget selected in the editor with the Tabs content section open, showing the Hide Tab Headings toggle and the Custom Tabs repeater.*
+
 ## How it works
 
 Place this widget on your Single Product template — it replaces WooCommerce's entire tabs area with a fully rebuilt, restyled version, including desktop tabs that automatically convert to an accordion on smaller screens.
 
-**Only need to add one extra tab to WooCommerce's existing tabs, without a full rebuild?** See the lighter-weight [Woo Add Product Tab](woo-add-product-tab.md) instead.
+![Custom product tabs on a live product page](../assets/img/woo-custom-product-tabs-frontend.png)
+*Screenshot: a product page showing styled tabs with a custom content tab active alongside the default Description and Reviews tabs.*
+It covers everything from bolting on a single extra tab to a complete rebuild: keep or hide any of the default WooCommerce tabs, add as many custom tabs as you like, and control which products each custom tab appears on by taxonomy.
 
 ## Content settings — Tabs
 
@@ -14,9 +19,31 @@ Place this widget on your Single Product template — it replaces WooCommerce's
 |---|---|---|
 | **Hide Tab Headings** | Off | Hides the heading text at the top of each tab panel (including WooCommerce's own "Reviews" heading). |
 | **Hide Description / Hide Additional Information / Hide Reviews** | Off each | Fully removes that specific default WooCommerce tab — not just visually, it won't render at all. |
-| **Custom Tabs** | Empty | A repeater — add as many extra tabs as you need, each with: **Title**, **Content Type** (Text Editor or Elementor Template), **Content** (rich text, for Text Editor), and **Template ID** (for Elementor Template — see below). |
+| **Custom Tabs** | Empty | A repeater — add as many extra tabs as you need, each with: **Title**, **Content Type** (Text Editor or Elementor Template), **Content** (rich text, for Text Editor), **Template ID** (for Elementor Template — see below), and a **Show On** rule to limit the tab to certain products (see [Showing a tab only on certain products](#showing-a-tab-only-on-certain-products)). |
 | **Accordion Below (px)** | 768 | The screen width below which tabs switch to an accordion layout. 768 suits tablet-portrait and below, 480 suits mobile-only, and 0 disables the accordion entirely (always shows tabs). |
 
+## Showing a tab only on certain products
+
+Each custom tab has a **Show On** setting that controls which products it appears on, based on the product's taxonomy terms — categories, tags, brands, or attribute values. This means one Custom Product Tabs widget on your shared Single Product template can serve every product, while individual tabs appear only where they're relevant.
+
+**Show On** offers three modes:
+
+| Mode | What it does |
+|---|---|
+| **All products** *(default)* | The tab shows on every product — the normal behaviour. |
+| **Only products with selected terms** | The tab shows *only* on products that have at least one of the terms you pick. |
+| **All except products with selected terms** | The tab shows on every product *except* those with one of the terms you pick. |
+
+When you choose either of the restricted modes, a **Terms** field appears listing every term across your product taxonomies, each labelled by its taxonomy (for example "Category: Hoodies" or "Color: Maroon") so same-named terms stay distinguishable. Pick one or more; a product matches when it has **any** of the selected terms.
+
+**Example:** a "Made on Demand" tab that should only appear on your print-on-demand products — set **Show On** to *Only products with selected terms* and choose your print-on-demand category (or several categories at once). Every other product simply won't show that tab.
+
+A couple of things worth knowing:
+
+- This applies to **custom tabs only**. The default WooCommerce tabs (Description, Additional Information, Reviews) are controlled by their Hide toggles, not by taxonomy.
+- The rule is respected in the Elementor editor preview too — so if the product being previewed doesn't match a tab's rule, that tab genuinely disappears from the preview. Set the rule last, or preview with a product that matches.
+- If a tab's Terms list is left empty, the tab shows everywhere (an empty rule does nothing).
+
 ## Adding an Elementor Template as a custom tab
 
 For a custom tab, choosing **Elementor Template** as the Content Type requires entering that template's numeric ID directly (rather than picking it from a list). To find it:
@@ -25,11 +52,23 @@ For a custom tab, choosing **Elementor Template** as the Content Type requires e
 2. Open the template you want to embed, or hover over it in the list.
 3. The number in the edit URL (`post=1234`) or shown in your browser's address bar is the Template ID — enter that number into the field.
 
+## Using shortcodes in a tab
+
+Custom tabs set to **Text Editor** run shortcodes, so anything available on your site as a shortcode can go straight into a tab's content.
+
+This is the practical way to give every product its own document without building a tab per product. Using the free plugin's Markdown shortcode:
+
+```
+[dj_markdown acf_field="changelog_url"]
+```
+
+Add a URL field to your products, drop that single line into a "Changelog" tab, and each product renders the file its own field points at. See the [Markdown Widget](../../dotjuice-elementor-tools/widgets/markdown-widget.md) documentation for the full list of shortcode options.
+
 ## Styling
 
 **Tab Navigation** — background, spacing, alignment, divider styling, and Normal/Hover/Active states for each tab button (including a separate colour control for the active tab's bottom border, useful for either blending it into the panel or removing the divider line entirely).
 
-**Panel** — background, typography, padding, border, and shadow for the content area beneath the tabs.
+**Panel** — background, text colour, typography, padding, border, and shadow for the content area beneath the tabs. The text colour also applies to the panel's own tab heading (e.g. the "Reviews" heading), unless overridden by the more specific Reviews section colours below.
 
 **Reviews** (hidden if you've turned off the Reviews tab) — review count heading, review card styling, avatar (with an option to hide it, size, and rounding), star rating colours, author/date text, review body text, an optional decorative quote mark, and full styling for the review submission form — its star picker, labels, input fields, and submit button.
 
@@ -37,10 +76,11 @@ For a custom tab, choosing **Elementor Template** as the Content Type requires e
 
 1. Add the widget to your Single Product Elementor Theme Builder template.
 2. Decide which default tabs to keep, and add any custom tabs you need.
-3. Set your Accordion breakpoint based on how your theme handles tablets — 768px is a safe default for most sites.
-4. Style the Tab Navigation and Panel sections to match your design, then move on to the Reviews section if you display product reviews.
+3. For any custom tab that shouldn't appear on every product, set its **Show On** rule and pick the relevant terms.
+4. Set your Accordion breakpoint based on how your theme handles tablets — 768px is a safe default for most sites.
+5. Style the Tab Navigation and Panel sections to match your design, then move on to the Reviews section if you display product reviews.
 
 ## Good to know
 
-- **If every tab ends up hidden**, nothing renders at all on the live product page — double check at least one tab (default or custom) is visible before publishing.
+- **If every tab ends up hidden** (whether by the Hide toggles or by taxonomy rules) nothing renders at all on that product page — make sure at least one tab is visible for the products you're viewing.
 - Custom tab content using the Elementor Template option needs that template to already be built and published — this widget only embeds it, it doesn't create it.

docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md

@@ -2,10 +2,17 @@
 
 Found in the Elementor panel under **Dotjuice → Woo Product Filter**. Requires WooCommerce.
 
+![The Woo Product Filter widget controls in the Elementor panel](../assets/img/woo-product-filter-controls.png)
+*Screenshot: the widget selected in the editor with the Filters repeater open, showing Filter Title, Filter By, and Display Type options.*
+
 ## How it works
 
 This widget renders one or more filter groups (category, tag, brand, or attribute) and, by default, refreshes your product grid via AJAX whenever a shopper makes a selection — no full page reload needed. It's designed to sit on your Shop page or a category archive, alongside your product grid.
 
+![The Woo Product Filter widget on the front end](../assets/img/woo-product-filter-frontend.png)
+*Screenshot: a shop page with active filter groups showing checkboxes and buttons, with the product grid filtered to show matching results.*
+As shoppers filter, the *available options in the other filters* update to reflect what's actually in stock for the current selection (see [How the options narrow](#how-the-options-narrow) below). Options that can't produce any results are hidden, so the filters never offer a dead end.
+
 ## Building your filter groups
 
 Each filter group is one item in the **Filters** repeater. Add as many as you need — one per category/attribute you want shoppers to filter by.
@@ -16,15 +23,52 @@ Each filter group is one item in the **Filters** repeater. Add as many as you ne
 | **Filter By** | Category | Category, Tag, Brand, or Attribute. |
 | **Taxonomy Slug** | — | Only for Attribute — the technical slug of the attribute (e.g. `pa_color`). |
 | **Display Type** | List | List (simple clickable list) or Buttons (clickable button/swatch style). |
-| **Match Logic** | Match Any | Whether selecting multiple terms in this group should show products matching *any* of them, or *all* of them. |
+| **Match Logic** | Match Any | Whether selecting multiple terms in this group shows products matching *any* of them, or *all* of them. |
 | **Show products without this attribute** | Yes | Attribute filters only. When a term is selected, decides whether products that don't have this attribute set at all stay visible (Yes) or are hidden (No). |
-| **Enable Colour Swatches** | Off | Buttons display only. Shows each term's assigned colour as a clickable swatch instead of a text button — colours come from the [Product Attribute Colours](../../../../dotjuice-elementor-tools/documentation/user-guide/product-attribute-colours.md) settings page in the free plugin. Terms sharing the same colour are merged into a single clickable swatch. |
-| **Show this filter** | Always | Always, only when any other filter is selected, or only when a specific other filter type has a selection — see "Dependent filters" below. |
-| **Hide unavailable terms** | Off | When on, terms with zero matching products (given the current selection) are removed entirely rather than just visually faded. |
+| **Enable Swatch Color** | Off | Buttons display only. Shows each term's assigned colour as a clickable swatch instead of a text button — colours come from the [Product Attribute Colours](../../dotjuice-elementor-tools/product-attribute-colours.md) settings page in the free plugin. Terms sharing the same colour are merged into a single clickable swatch. |
+| **Show this filter** | Always | Always, only when any other filter is selected, or only when a specific other filter type has a selection — see [Dependent filters](#dependent-filters) below. |
+| **Show after this filter type** | Category | Only used when *Show this filter* is set to depend on another filter — the filter type that triggers this one. |
+| **Trigger taxonomy slug** | — | For an Attribute trigger, the slug of the attribute that reveals this filter. |
+| **Link to term archive** | Off | When on, clicking a term navigates to that term's own archive page instead of filtering the grid in place — see [Link to term archive](#link-to-term-archive) below. |
+| **Hide unselected items** | Off | Turns this group into an "active filters" bar that shows only the currently-selected terms as removable chips — see [Active-filters bar](#active-filters-bar-hide-unselected-items) below. |
+
+## How the options narrow
+
+When a shopper picks a value in one filter, every *other* filter updates to show only the options still available — but a filter never narrows itself. For example, choosing a **category** (or being on a category/range archive) reduces the **colour** swatches to just the colours those products come in; then picking a colour doesn't shrink the colour list further, it simply reflects the category you're in. This means the colours always mirror the "parent" filters (category, range, etc.) you've chosen, which is what shoppers expect.
+
+Options that can't produce any results with the current selection are **hidden** entirely, and a filter group whose options all disappear collapses (its heading hides too), so shoppers never see empty or dead-end choices.
 
 ## Dependent filters
 
-To build a filter group that only appears once another one is used — for example, showing a "Size" filter only after a category is chosen — set **Show this filter** to "When a specific filter is selected" and choose which filter type triggers it. If the triggering selection is cleared, the dependent group's own selections are cleared too.
+To build a filter group that only appears once another one is used — for example, showing a "Size" filter only after a category is chosen — set **Show this filter** to "When a specific filter is selected" and choose which filter type (and, for attributes, which **Trigger taxonomy slug**) triggers it. If the triggering selection is cleared, the dependent group's own selections are cleared too.
+
+## Link to term archive
+
+Set per filter group. When **Link to term archive** is on, clicking a term takes the shopper to that term's normal archive page (e.g. the category or range page) instead of filtering the current grid via AJAX. This is handy when a group is really meant for *navigation* (e.g. jumping between ranges) rather than in-place filtering.
+
+- The group's **Clear** link / ✕ then returns to the main Shop page rather than just clearing a selection.
+- It's safe in the Elementor editor: clicking a linked term while designing won't navigate the editor away.
+
+## Active-filters bar (Hide unselected items)
+
+Turn **Hide unselected items** on for a filter group and it shows **only the terms currently selected**, each as a removable chip with an ✕ — clicking a chip deselects that term. When nothing is selected, the group (and its heading) collapse out of view. The group's own Clear link is hidden in this mode, since each chip is individually removable.
+
+The intended pattern is **two instances of the widget**:
+
+- The **main filter** (for example inside an off-canvas panel) leaves this off and shows all terms for browsing and selecting.
+- A **second instance above the product grid** turns **Hide unselected items** on for each group, so it acts as an "active filters" summary bar — empty until the shopper picks something, then showing their choices as ✕ chips they can clear individually.
+
+Because both instances share the same selection state, selecting a term in one instantly appears as a chip in the other, and clearing a chip updates both.
+
+## Reset & clear options
+
+These sit below the Filters repeater and apply to the whole widget:
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Show Reset Button** | On | Shows the "Reset Filters" button that clears every group at once. Turn off if you'd rather rely on the per-group clear links / chips. |
+| **Cascade Clear** | Off | When on, clearing one filter group also clears every group *below* it in the list. Useful when lower filters only make sense in the context of a higher one (e.g. clearing Category also clears the Colour choices made within it). |
+| **Clear Link Style** | Text | Whether each group's clear control is a text link ("Clear") or a compact ✕ icon. |
 
 ## AJAX & URL settings
 
@@ -34,22 +78,33 @@ To build a filter group that only appears once another one is used — for examp
 | **Live update** | Off | AJAX mode only. When on, the grid refreshes automatically the moment a filter is clicked. When off, shoppers make their selections and click an "Apply Filters" button to refresh. |
 | **Update browser URL** | On | AJAX mode only. Keeps the URL in sync with the current filter selection as shoppers filter, so the page can be bookmarked, shared, or reloaded and show the same results. |
 | **Products container selector** | Empty (auto-detect) | Advanced: the CSS selector of your product grid, if the widget doesn't auto-detect it correctly. Leave empty unless you're troubleshooting a grid that isn't updating. |
-| **Contextual filtering** | Off | When placed on a category archive page, scopes filter options and counts to that category's products only, rather than your whole catalogue. |
+| **Contextual filtering** | Off | When placed on a category/term archive page, scopes the *initial* filter options to that archive's products only, rather than your whole catalogue. |
+
+## Pagination
+
+When AJAX is on, clicking a page in a [Woo Page Numbers](../../dotjuice-elementor-tools/widgets/woo-page-numbers.md) widget (or your theme's product pagination) loads that page's products in place — no full reload — while keeping your current filters applied. With **Update browser URL** on, the address bar updates to the normal pretty archive form, e.g. `/t-shirts/page/2/?pa_color=blue`, so paged views are shareable and bookmarkable, and the browser back/forward buttons move between pages. (On sites using plain permalinks it falls back to `?paged=2`.)
 
 ## Styling
 
-Filter Group headings, Buttons (Normal/Hover/Active states), Swatches (Normal/Selected states), and Faded terms (opacity, greyscale, scale for unavailable options, plus a toggle for whether faded/unavailable terms can still be clicked).
+Style controls live under the Style tab:
+
+- **Filter group** — Title Typography, Title Colour, **Grid Gap** (space between the terms within a group), and **Space Between Groups** (vertical gap between one filter group and the next).
+- **Buttons** — Button Typography; Text and Background colours for **Normal**, **Hover** and **Active** (selected) states; Border radius; Padding.
+- **Clear Link** — Typography, Size, Colour (Normal / Hover), and Spacing Above (the gap between the terms and the clear link / ✕).
+- **Swatches buttons** — for colour swatches: Swatch Size and Border radius for the **Normal** and **Selected** states, plus a Margin control for selected swatches.
 
 ## Setting it up
 
 1. Add the widget to your Shop page or category archive template, near your product grid.
 2. Add a filter group for each way you want shoppers to filter — start with Category, then add Attribute groups for things like colour or size.
-3. For colour attributes, set up your colours first on the [Product Attribute Colours](../../../../dotjuice-elementor-tools/documentation/user-guide/product-attribute-colours.md) page, then enable **Enable Colour Swatches** on that filter group.
+3. For colour attributes, set up your colours first on the [Product Attribute Colours](../../dotjuice-elementor-tools/product-attribute-colours.md) page, then enable **Enable Swatch Color** on that filter group.
 4. Leave AJAX and URL settings at their defaults for most stores — instant, bookmarkable filtering.
-5. Test: apply a filter, copy the URL, and open it in a new tab (or with JavaScript disabled) to confirm it reproduces the same filtered results.
+5. (Optional) Add a second instance of the widget above the grid with **Hide unselected items** turned on for each group, to give shoppers a clear "active filters" bar.
+6. Test: apply a filter, copy the URL, and open it in a new tab (or with JavaScript disabled) to confirm it reproduces the same filtered results.
 
 ## Good to know
 
+- **Options reflect your other selections, not their own.** Picking a colour won't shrink the colour list — the colours mirror the category/range you're in. This "disjunctive" behaviour is automatic and needs no setup.
 - **Filtered URLs work even without JavaScript** — if a shopper shares a filtered link, or your page is cached, the filter still applies correctly on a plain page load, not just via AJAX. This is deliberate and doesn't need any extra setup.
 - Colour swatches only work for **Attribute** filter groups (not category/tag/brand), and require colours to already be configured on the Product Attribute Colours page — a term with no colour assigned won't show a meaningful swatch.
 - If your product grid doesn't refresh correctly after filtering, check the **Products container selector** field — leaving it empty works for most themes' standard WooCommerce/Elementor product grids, but an unusual custom grid layout may need this set explicitly.

docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md

@@ -4,10 +4,16 @@ This widget renders the **content shown inside** a Quick View popup. It only wor
 
 Found in the Elementor panel under **Dotjuice → Woo Quick View Popup**. Requires WooCommerce.
 
+![The Woo Quick View Popup widget content settings](../assets/img/woo-quick-view-popup-controls.png)
+*Screenshot: the widget selected in the editor with the Content Source dropdown and Quick View Template selector visible.*
+
 ## How it works
 
 Place this widget inside an Elementor popup (nothing else needs to go in that popup — this widget fills it entirely). It renders as an iframe showing whichever product a shopper clicked a Quick View button for.
 
+![The Quick View popup content on the front end](../assets/img/woo-quick-view-popup-frontend.png)
+*Screenshot: the inside of a Quick View popup showing the product image gallery, title, price, and add-to-cart options rendered by the popup widget.*
+
 ## Content settings
 
 | Setting | Default | What it does |

docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view.md

@@ -4,12 +4,18 @@ Two widgets work together to build Quick View: **Woo Quick View** (this one —
 
 Requires WooCommerce. **Requires Elementor Pro** for the popup to actually open — without Elementor Pro, the quick-view button gracefully falls back to a normal link straight to the product page instead, so nothing is ever broken, it simply won't show a popup.
 
+![The Woo Quick View widget settings in the Elementor panel](../assets/img/woo-quick-view-controls.png)
+*Screenshot: the widget selected in the editor with the Quick View settings open, showing the Enable Quick View toggle and the popup selector.*
+
 ## How it works, end to end
 
 1. You build a popup (an Elementor Pro popup content type) containing the **Woo Quick View Popup** widget.
 2. You place the **Woo Quick View** widget anywhere you like, and point it at that popup.
 3. The Quick View widget then automatically injects a quick-view button onto every product in your product loops (grids, carousels) sitewide — you don't need to manually add a button to each product card.
 
+![A Quick View popup open on a product](../assets/img/woo-quick-view-frontend.png)
+*Screenshot: a shop grid with a Quick View popup open, showing the product image, price, variations, and add-to-cart button inside the overlay.*
+
 ## Setting it up
 
 1. **Create the popup**: in Elementor, create a new Popup (Templates → Popups → Add New in your Elementor library).

docs/dotjuice-elementor-tools/getting-started.md

@@ -1,42 +1,79 @@
 # Getting Started
 
+Dotjuice Tools for Elementor adds ten widgets to the Elementor editor, plus three settings pages for the features that need configuration outside the page builder.
+
+![The Dotjuice widget category in the Elementor editor panel](./assets/img/getting-started-widget-panel.png)
+*Screenshot: the Elementor editor with the widgets panel open and the **Dotjuice** category expanded, showing the full widget list.*
+
 ## Requirements
 
-Dotjuice Elementor Tools requires **Elementor** (the free page builder plugin) to be installed and active. It doesn't require WooCommerce or ACF, but several widgets only appear once those plugins are active too — see [Finding your widgets](#finding-your-widgets) below.
+| | |
+|---|---|
+| **Required** | [Elementor](https://wordpress.org/plugins/elementor/) (the free page builder) installed and active |
+| **Optional** | WooCommerce — unlocks the six Woo widgets and the WooCommerce Hacks settings page |
+| **Optional** | Advanced Custom Fields — lets the Markdown shortcode read its URL from an ACF field |
+
+The plugin does nothing on its own without Elementor: its widgets are registered on Elementor's own widget-registration hook, so if Elementor is inactive the Dotjuice category simply won't exist.
 
 ## Finding your widgets
 
-Open any page in the Elementor editor and look for the **Dotjuice** category in the widgets panel on the left. Every widget from this plugin lives there.
+Open any page in the Elementor editor and look for the **Dotjuice** category in the widgets panel. Every widget from this plugin lives there.
 
-If a widget you expect to see is missing:
+If a widget you expect is missing, it's almost always the WooCommerce dependency. These six only register when WooCommerce is active:
 
-- **All WooCommerce-related widgets** (anything with "Woo" in the name, plus **Woo Taxonomy List**) only appear once **WooCommerce** is installed and active — even Woo Taxonomy List, which can be used for non-shop content like blog categories, only shows up with WooCommerce present. If you want a general-purpose taxonomy list widget on a site without WooCommerce, install WooCommerce or get in touch with support.
-- The **Image Carousel Transform** widget only has a visible effect on pages that also use Elementor Pro's native Image Carousel widget elsewhere.
+- Woo Products Transform
+- Woo Add To Cart transform
+- Woo Categories Transform
+- Woo My Account Transform
+- Woo Page Numbers
+- Woo Taxonomy List
+
+**Woo Taxonomy List is in that list even though it isn't shop-specific.** It can drive non-shop content such as blog categories, but it still only appears when WooCommerce is present. On a site without WooCommerce it won't be available.
+
+The remaining four have no dependencies beyond Elementor: Screenshot Capture, Dark Mode Toggle, Keyword Linker, and Markdown.
 
 ## Where the plugin's settings live
 
-In your WordPress admin menu, under **Dotjuice**:
+Settings sit under the shared **Dotjuice** menu in your WordPress admin sidebar. That menu is shared by all Dotjuice plugins — whichever one loads first creates it, so if you also run Dotjuice Performance you'll see both listed under the same parent.
 
-- **Elementor Tools** — the plugin's own dashboard (Getting Started, Widgets overview, System Status, Support)
-- **Screenshot API** — required setup for the Screenshot Capture widget (see [Screenshot API Settings](screenshot-api-settings.md))
-- **WooCommerce Hacks** — account page tweaks and product attribute colours (only visible with WooCommerce active — see [WooCommerce Account Settings](woocommerce-account-settings.md) and [Product Attribute Colours](product-attribute-colours.md))
+![The Dotjuice admin menu expanded in the WordPress sidebar](./assets/img/getting-started-admin-menu.png)
+*Screenshot: the WordPress admin sidebar with the **Dotjuice** menu expanded, showing its submenu items.*
+
+| Menu item | What it's for |
+|---|---|
+| **Tools for Elementor** | The plugin's own dashboard — widget overview, system status, and support links. |
+| **Integrations** | A tabbed page for widgets that talk to outside services. Screenshot API settings are the first tab — see [Screenshot API Settings](screenshot-api-settings.md). |
+| **WooCommerce Hacks** | Account page tweaks and product attribute colours. Only appears when WooCommerce is active — see [WooCommerce Account Settings](woocommerce-account-settings.md) and [Product Attribute Colours](product-attribute-colours.md). |
+
+:::note
+Older versions of this plugin had a standalone **Screenshot API** menu item. It's now the first tab of **Integrations**, which exists so future API-backed widgets can add their own tabs rather than each adding a menu entry.
+:::
 
 ## Recommended first steps
 
-1. If you plan to use **Screenshot Capture**, set up your API key first — see [Screenshot API Settings](screenshot-api-settings.md). The widget won't display anything without it.
-2. If you run a WooCommerce store, review [WooCommerce Account Settings](woocommerce-account-settings.md) — most stores end up wanting at least one of these tweaks (hiding unused account tabs, excluding a category from the shop page).
-3. Browse the widget guides below for the ones relevant to your build.
+1. **Setting up Screenshot Capture?** Configure your API key first under **Dotjuice → Integrations**. The widget renders nothing at all without a key — see [Screenshot API Settings](screenshot-api-settings.md).
+2. **Running a WooCommerce store?** Look through [WooCommerce Account Settings](woocommerce-account-settings.md). Most stores want at least one of these — hiding unused My Account tabs, or keeping a category off the main shop page.
+3. **Using colour swatches anywhere?** Assign your colours once under [Product Attribute Colours](product-attribute-colours.md); every widget that shows swatches reads from that single list.
+4. Browse the widget guides below for whatever your build needs.
 
 ## Widget guides
 
-- [Screenshot Capture](widgets/screenshot-capture.md)
-- [Dark Mode Toggle](widgets/dark-mode-toggle.md)
-- [Keyword Linker](widgets/keyword-linker.md)
-- [Markdown Widget](widgets/markdown-widget.md)
-- [Image Carousel Transform](widgets/image-carousel-transform.md)
-- [Woo Add to Cart Transform](widgets/woo-add-to-cart-transform.md)
-- [Woo Categories Transform](widgets/woo-categories-transform.md)
-- [Extended Product Loop](widgets/extended-product-loop.md)
-- [Woo My Account Transform](widgets/woo-my-account-transform.md)
-- [Woo Page Numbers](widgets/woo-page-numbers.md)
-- [Woo Taxonomy List](widgets/woo-taxonomy-list.md)
+**General purpose**
+
+- [Screenshot Capture](widgets/screenshot-capture.md) — live screenshots of any website, captured through an API
+- [Dark Mode Toggle](widgets/dark-mode-toggle.md) — a front-end light/dark switch driven by Elementor's global colours
+- [Keyword Linker](widgets/keyword-linker.md) — turn chosen words into links across a page automatically
+- [Markdown](widgets/markdown-widget.md) — render a live Markdown file, with a shortcode for per-post documents
+
+**WooCommerce** (require WooCommerce active)
+
+- [Woo Products Transform](widgets/woo-products-transform.md) — an attribute-aware product grid with hover and rollover effects
+- [Woo Add to Cart Transform](widgets/woo-add-to-cart-transform.md) — variation dropdowns rebuilt as clickable buttons or colour swatches
+- [Woo Categories Transform](widgets/woo-categories-transform.md) — styled, animated category tiles
+- [Woo My Account Transform](widgets/woo-my-account-transform.md) — full styling control over the My Account area
+- [Woo Page Numbers](widgets/woo-page-numbers.md) — styleable product pagination that co-operates with AJAX filtering
+- [Woo Taxonomy List](widgets/woo-taxonomy-list.md) — cascading term lists from any taxonomy
+
+## Upgrading to Pro
+
+Several widgets have controls that are visible but inert in the free version — colour swatches on Woo Add to Cart Transform are the usual one people hit. Where that applies it's called out in that widget's guide. [Dotjuice Tools for Elementor Pro](../dotjuice-elementor-tools-pro/getting-started.md) is an add-on rather than a replacement: the free plugin must stay installed and active.

docs/dotjuice-elementor-tools/product-attribute-colours.md

@@ -2,25 +2,46 @@
 
 **Dotjuice → WooCommerce Hacks → Attribute Colours** (only visible with WooCommerce active)
 
+Assign a hex colour to each term of any product attribute, so colour-based options can render as swatches rather than text.
+
+![The Attribute Colours table with colour pickers per term](./assets/img/product-attribute-colours.png)
+*Screenshot: the Attribute Colours tab with an attribute selected, showing the term table — each row with its colour picker, hex field, Shared indicator and Clear button.*
+
 ## What this does
 
-Lets you assign a hex colour to each term of any product attribute on your store (Colour, Material, or any custom attribute you've created). This is a configuration page — see the note below about where these colours are actually displayed.
+This is a **configuration page only**. It stores a colour against each attribute term (Colour, Material, or any custom attribute you've created). It doesn't display anything on the front end by itself — see [Where these colours appear](#where-these-colours-actually-appear) below.
+
+Storing them centrally means every widget that draws a swatch reads from one list, so a colour change here updates everywhere at once.
 
 ## Setting a colour
 
-1. Choose the attribute you want to configure from the dropdown at the top (e.g. "Colour").
-2. Every term for that attribute is listed in a table, each with a colour picker and a matching hex code field — you can use either; they stay in sync.
-3. Enter or pick a colour for each term you want to configure. A "Clear" button next to each row removes its colour.
+1. Pick the attribute to configure from the dropdown at the top — for example "Colour".
+2. Every term for that attribute is listed, each with a colour picker and a hex field. The two stay in sync, so use whichever you prefer.
+3. Set a colour for each term you want swatched. **Clear** on a row removes its colour.
 4. Save.
 
+Terms left without a colour simply render as normal text buttons wherever swatches are shown.
+
 ## Sharing one colour across several terms
 
-If several terms should display as the same swatch colour (for example, "Ash", "Carbon Grey", and "Slate" all rendering as the same grey), just give them the identical hex value. The table shows a "Shared" indicator next to terms that currently share a colour with others, so you can see at a glance which terms are grouped together.
+When several terms should display as the same swatch — "Ash", "Carbon Grey" and "Slate" all showing as one grey — give them an identical hex value.
+
+The table shows a **Shared** indicator beside any term whose colour matches another, so you can see the groupings at a glance. Widgets that render swatches merge terms sharing a colour into a single clickable swatch, which is usually what you want: shoppers see one grey, not three near-identical ones.
 
 ## Sorting the list
 
-Use the **Sort by** control (Name or Hex Value) to reorder the table while you work — sorting by hex value groups terms with the same colour together visually, useful for checking your "shared colour" groupings are set up the way you intended.
+The **Sort by** control (Name or Hex Value) reorders the table while you work. Sorting by hex groups identical colours together, which makes it easy to verify your shared-colour groupings are what you intended before saving.
 
-## ⚠ Where these colours actually appear
+## Where these colours actually appear
 
-This page only **stores** the colour assignments — it doesn't display them anywhere on its own. To show them as clickable colour swatches on your product pages, you need the **Woo Add to Cart Transform** widget's "Show Colour Swatches" option, which is a [Dotjuice Elementor Tools Pro](../dotjuice-elementor-tools-pro/getting-started.md) feature. In the free version, you can fully configure your colours here ready for when you upgrade, but your product options will display as plain buttons rather than colour swatches until Pro is active.
+:::caution Swatch display is a Pro feature
+This page stores the assignments; it doesn't render them. To show them as clickable swatches you need the **Show Colour Swatches** option on [Woo Add to Cart Transform](widgets/woo-add-to-cart-transform.md), or the swatch option on the Pro product filter — both part of [Dotjuice Tools for Elementor Pro](../dotjuice-elementor-tools-pro/getting-started.md).
+
+In the free version you can configure everything here ready for an upgrade, but product options display as plain text buttons until Pro is active.
+:::
+
+## Good to know
+
+- **Colours are stored per term, not per product.** Set "Navy" once and every product using that term gets the same swatch.
+- **Adding a new attribute term later leaves it uncoloured.** Come back to this page and set its colour, or it renders as a text button while its neighbours show swatches.
+- The hex field accepts values with or without the leading `#`.

docs/dotjuice-elementor-tools/screenshot-api-settings.md

@@ -1,29 +1,37 @@
 # Screenshot API Settings
 
-**Dotjuice → Screenshot API**
+**Dotjuice → Integrations → Screenshot API**
 
-This page configures the credentials the [Screenshot Capture](widgets/screenshot-capture.md) widget needs to function, and lets you manage the local cache of captured screenshots.
+This page holds the credentials the [Screenshot Capture](widgets/screenshot-capture.md) widget needs, and manages the local cache of captured screenshots.
+
+![The Screenshot API tab on the Integrations page](./assets/img/screenshot-api-settings.png)
+*Screenshot: the Integrations page with the Screenshot API tab active, showing the API Key and Secret Key fields and the Cache Management panel below.*
+
+:::note Moved in the July 2026 release
+This used to be a standalone **Screenshot API** item in the Dotjuice menu. It's now the first tab of **Integrations**, a shared home for widgets that talk to outside services. The settings themselves are unchanged.
+:::
 
 ## Setting up your API key
 
-1. Sign up for a Screenshot Machine account and get an API key (a link to their site is provided on the settings page).
-2. Paste your **API Key** into the field and save. A warning banner at the top of the page will disappear once a key is saved.
-3. If your Screenshot Machine account has a **Secret Key** configured for additional request security, enter it in the optional **Secret Key** field too — most accounts don't need this.
+1. Sign up for a Screenshot Machine account and get an API key — the settings page links to their site.
+2. Paste the key into the **API Key** field and save. The warning banner at the top of the page disappears once a key is stored.
+3. If your Screenshot Machine account has a **Secret Key** configured for request signing, enter it in the optional field too. Most accounts don't use this.
 
-Until an API key is entered, every Screenshot Capture widget on your site will fail to display an image.
+**Until an API key is saved, every Screenshot Capture widget on your site fails to display an image.** That's the single most common cause of a blank screenshot widget.
 
 ## Cache management
 
-This section shows:
+The panel shows:
 
 - How many screenshots are currently cached
 - Their total size on disk
-- Where they're stored (inside your uploads folder)
+- Where they're stored, inside your uploads folder
 - A **Clear All Cached Screenshots** button
 
-Clearing the cache deletes every cached screenshot file and removes the corresponding entries from your Media Library. Every widget will re-capture its screenshot (spending a fresh API call) the next time its page is viewed. Use this if you've made site-wide changes to target pages and want everything refreshed at once, rather than refreshing screenshots one at a time from the editor.
+Clearing removes every cached file and its Media Library entry. Each widget then re-captures on the next page view, spending a fresh API call. Use it when you've changed many target pages at once and want everything refreshed — rather than refreshing screenshots individually from the editor.
 
 ## Things to know
 
-- Every screenshot capture — whether from a visitor loading an uncached page, or your own manual refresh — counts as one billed API call against your Screenshot Machine plan. Keep this in mind if you have many Screenshot Capture widgets with a low or zero Cache Limit.
-- The Secret Key field is optional and only relevant if you've specifically enabled request signing in your Screenshot Machine account settings.
+- **Every capture is one billed API call** against your Screenshot Machine plan, whether triggered by a visitor loading an uncached page or by your own manual refresh. Worth watching if you run many Screenshot Capture widgets with a low or zero Cache Limit.
+- **Clearing the cache is site-wide and immediate.** On a site with a lot of screenshots, the next visitor to each page absorbs the capture wait — consider warming them yourself afterwards.
+- The Secret Key field is optional and only relevant if you've explicitly enabled request signing in your Screenshot Machine account.

docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md

@@ -1,34 +1,68 @@
 # Dark Mode Toggle
 
+A front-end light/dark switch that recolours your site by overriding Elementor's global colours.
+
 Found in the Elementor panel under **Dotjuice → Dark Mode Toggle**.
 
+![The Dark Mode Toggle widget controls in the Elementor panel](../assets/img/dark-mode-toggle-controls.png)
+*Screenshot: the widget selected in the editor with the **Icons** section open, showing the Normal/Dark icon pickers and colour controls.*
+
 ## How it works
 
-This widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps Elementor's four Global Color variables (Primary, Secondary, Text, Accent) to the dark-mode values you configure on the widget. It remembers the visitor's choice, so it stays applied on their next visit.
+The widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps your global colours for the dark-mode values you configure on the widget. The choice is stored in the visitor's browser, so it survives navigation and returns on their next visit — including on pages and templates that don't have the toggle on them at all, as long as the toggle exists somewhere on the site. Dark mode is applied before the page paints, so there's no flash of light-mode colours first.
 
-**Important:** this widget only changes colors for elements styled using Elementor's Global Colors. If part of your design uses a hardcoded color instead of a Global Color, that part won't respond to dark mode.
+It works with **both** of Elementor's global-colour systems:
 
-## Content settings
+- **Legacy 3.x global colours** — the four classic Global Colors (Primary, Secondary, Text, Accent) used by traditional Elementor widgets.
+- **Elementor 4.x global variables** — the named colour variables (e.g. `red`, `sea-green`) introduced with the newer atomic widgets, defined under **Site Settings → Global Variables**.
+
+Modern pages commonly mix older widgets (which read the legacy colours) with newer atomic widgets (which read 4.x variables), so the widget can override both at once from a single toggle.
+
+:::caution The single most important thing to understand
+Dark mode only changes elements styled with a **global colour or global variable**. Anything using a hardcoded hex value won't respond at all. If your toggle seems to "only half work", that's almost always the cause — the more consistently your design uses globals, the more complete the effect.
+:::
+
+## Content settings — Icons
 
 | Setting | Default | What it does |
 |---|---|---|
-| **Light Mode Icon** | Moon icon | The icon shown when the site is currently in light mode (click to switch to dark). |
-| **Dark Mode Icon** | Sun icon | The icon shown when the site is currently in dark mode (click to switch back to light). |
-| **Icon Color / Hover Color** | — | Styling for the toggle icon itself. |
-| **Icon Size** | — | Responsive sizing for the toggle icon. |
+| **Normal Mode Icon** | Moon | Shown while the site is in light mode. Clicking it switches to dark. |
+| **Dark Mode Icon** | Sun | Shown while the site is in dark mode. Clicking it switches back to light. |
+| **Icon Color** | — | Colour of the toggle icon itself (not affected by dark mode). |
+| **Hover Color** | — | Icon colour on hover. |
+| **Icon Size** | 24px | Responsive — set a different size per breakpoint if needed. |
 
-## Dark Mode Colors (Style tab)
+## Dark Mode Colors
 
-Four color fields — **Primary**, **Secondary**, **Text**, and **Accent** — define what your site looks like once dark mode is switched on. Set each to the dark equivalent of the matching Elementor Global Color. If you leave any of these blank, a sensible built-in dark default is used instead.
+**Global Colour System** decides which colour systems the toggle overrides:
+
+| Choice | What it does |
+|---|---|
+| **Both** *(default)* | Applies the legacy four colours **and** your 4.x variable overrides together. Best for pages mixing old and new widgets. |
+| **Legacy only — Elementor 3.x** | Overrides just Primary, Secondary, Text and Accent. |
+| **Variables only — Elementor 4.x** | Overrides just the global variables, leaving the classic four untouched. |
+
+**Legacy 3.x global colors** — four colour fields (**Primary**, **Secondary**, **Text**, **Accent**) define the dark equivalent of each classic Global Color. Leave any blank to fall back to a sensible built-in dark default.
+
+**Elementor 4.x global variables** — a repeater. Add one row per variable you want to change: pick the variable from your site's list, then set its dark-mode colour. Add as many rows as you need; variables you don't list keep their normal values.
+
+![The Dark Mode Colors section with variable override rows](../assets/img/dark-mode-toggle-colours.png)
+*Screenshot: the **Dark Mode Colors** section showing the Global Colour System dropdown, the four legacy colour fields, and two or three variable override rows.*
+
+:::note
+New variables created *after* you opened the editor won't appear in the dropdown until you reload it — Elementor builds the widget's option list once, when the editor loads.
+:::
 
 ## Setting it up
 
-1. Add the widget somewhere visible and consistent — a header or footer works well, so it's reachable from every page.
-2. Under the Style tab, set your four Dark Mode Colors to a palette that works well as a dark theme.
-3. Save and test: click the toggle on the live site and check that the elements using your Global Colors switch correctly.
+1. Add the widget somewhere reachable from every page — a header or footer is the usual choice.
+2. Choose your **Global Colour System**. Leave it on **Both** unless you know your site uses only one widget generation.
+3. Set the legacy dark colours, and/or add a variable row for each global variable that needs a dark value.
+4. Save, then click the toggle on the live site and check that everything using globals switches cleanly.
 
 ## Good to know
 
-- **Whichever toggle instance was clicked most recently determines the colors used site-wide.** If you place more than one Dark Mode Toggle widget with different color settings, the last one clicked "wins" for the whole site until another is clicked. For a single consistent dark mode, use the same color settings on every instance, or better, only place the widget in one shared location like your header.
-- You can deep-link directly into dark mode by adding `?dark=0` to any URL (or `?dark=1`, `?dark=2`, etc. if there's more than one toggle instance on that specific page) — useful for sharing a dark-mode preview link.
-- The dark mode choice is remembered per browser (not per WordPress account), so it persists across visits on the same device but doesn't follow a visitor between devices.
+- **The most recently clicked toggle determines the colours used site-wide.** If you place several toggles with different settings, the last one clicked wins until another is clicked. For consistency, either use identical settings everywhere or place a single toggle in a shared header.
+- **Changed your colours after already switching dark mode on?** Toggle it off and on once, or clear the browser's site data. The last-used colours are cached in the browser for speed, so a stale set can linger.
+- **You can deep-link into dark mode** by adding `?dark=0` to any URL — or `?dark=1`, `?dark=2` and so on where a page holds more than one toggle. Handy for sharing a dark-mode preview.
+- **The preference is per browser, not per WordPress account.** It persists across visits on the same device but doesn't follow a visitor to another device or browser.

docs/dotjuice-elementor-tools/widgets/extended-product-loop.md

@@ -1,31 +0,0 @@
-# Extended Product Loop
-
-Found in the Elementor panel under **Dotjuice → Extended Product Loop**. Requires WooCommerce.
-
-## How it works
-
-This widget renders its own product grid — separate from Elementor's or WooCommerce's native product loop widgets. It shows all your regular published products, plus an extra tile for every individual product variation that has a value set for the attribute you choose. Each tile shows that variation's own image, name, and price, linking through to the parent product page.
-
-## Content settings
-
-| Setting | Default | What it does |
-|---|---|---|
-| **Attribute Name** | `pa_color` | The attribute taxonomy to pull variations from, using its technical slug (WooCommerce attributes are typically prefixed `pa_`, e.g. `pa_color`, `pa_size`). |
-
-There's no Style tab on this widget — the grid uses WooCommerce's standard product-grid CSS classes, so it inherits your theme's existing product grid styling.
-
-## What to expect in the grid
-
-If a product has three variations matching your chosen attribute (say, three colours), it can appear as **up to four tiles**: the parent product once, plus one tile per matching variation. This is intentional — it's what makes a "shop by colour" browsing experience possible — but it's worth knowing in advance so it doesn't look like a duplication bug when you first set it up.
-
-**This widget's tiles show image, name, and price only** — no Add to Cart button, sale badges, or star ratings, since the grid is built independently of WooCommerce's standard loop template. Link the tile through to the product page for the full buying experience.
-
-## Setting it up
-
-1. Decide which attribute you want to browse by (commonly colour or size) and find its technical slug — check **Products → Attributes** in your WordPress admin, or look at the attribute's edit URL.
-2. Enter that slug into **Attribute Name**.
-3. Place the widget on a page and confirm the variation tiles appear as expected.
-
-## Good to know
-
-- If the attribute slug you enter doesn't exist on your store, the widget quietly falls back to showing only your regular product list — no error is shown, so double-check your spelling if variation tiles aren't appearing.

docs/dotjuice-elementor-tools/widgets/keyword-linker.md

@@ -1,33 +1,52 @@
 # Keyword Linker
 
+Turn chosen words into links automatically, across every post using a template.
+
 Found in the Elementor panel under **Dotjuice → Keyword Linker**.
 
+![The Keyword Linker repeater with several keyword rows](../assets/img/keyword-linker-controls.png)
+*Screenshot: the widget's **Keyword Links** repeater expanded, showing two or three keyword rows with their URL, Bold and Link all occurrences settings.*
+
 ## How it works
 
-This widget doesn't display anything visible on the page itself — it works in the background, scanning your post and page content for the keywords you've defined and converting matching occurrences into links. Add it once to a template that renders post content (a Single Post or Single Page template), and it applies to every post/page using that template.
+This widget renders nothing visible. It works in the background: it hooks into WordPress's content output, scans for the keywords you've defined, and converts matching occurrences into links. Add it once to a template that renders post content — a Single Post or Single Page Theme Builder template — and it applies to every post or page using that template.
 
-Matching happens inside paragraph and heading text only — text inside list items, tables, or other structural elements isn't scanned. Matching is whole-word and case-insensitive, and any text that's already part of an existing link is left alone.
+That "invisible widget on a template" model is the part people trip over. You are not adding it to one article; you are adding it to the template all your articles share.
+
+**Matching rules:**
+
+- Only text inside paragraph (`<p>`) and heading tags is scanned. Text inside list items, tables, or custom block markup is left alone.
+- Matching is **whole-word**, so `cat` will not match `category`.
+- Matching is **case-insensitive**, and the matched text keeps its original capitalisation in the resulting link — you don't need to define both "Elementor" and "elementor".
+- Text that is already inside a link is never re-linked, so you won't get nested anchors.
 
 ## Content settings — Keyword Links
 
-A repeater list; add one row per keyword you want linked.
+A repeater. Add one row per keyword you want linked.
 
-| Setting | What it does |
-|---|---|
-| **Keyword** | The exact word or phrase to search for. Matches are whole-word only (so "cat" won't match "category") and case-insensitive. |
-| **Link** | The destination URL, with options to open in a new tab and/or add a "nofollow" attribute. |
-| **Bold** | Makes the generated link bold. |
-| **Link All Occurrences** | If on, every matching occurrence on the page gets linked. If off, only the first few (see Max Links below). |
-| **Max Links** | Only shown when "Link All Occurrences" is off. The maximum number of times this specific keyword gets linked per page (1–50, default 3). |
+| Setting | Default | What it does |
+|---|---|---|
+| **Keyword** | — | The word or phrase to look for. Whole-word, case-insensitive. |
+| **URL** | — | Where the link points. Supports Elementor's usual open-in-new-tab and nofollow options. |
+| **Bold link text** | Off | Renders the generated link in bold. |
+| **Link all occurrences** | Off | On: every match on the page is linked. Off: only the first few, capped by Max links. |
+| **Max links** | 3 | Only shown when **Link all occurrences** is off. How many times this keyword may be linked on a single page (1–50). |
+
+:::tip Why you usually want the cap
+Linking every occurrence of a common word reads as spam to both visitors and search engines. The default of three is deliberate — it catches the keyword early in the article where it matters, and leaves the rest as plain text.
+:::
 
 ## Setting it up
 
-1. Add the widget to a template that renders your post/page content (typically your Single Post or Single Page Elementor template — this is a "Theme Builder" style template in Elementor, not a specific individual post).
-2. Add a row for each keyword you want automatically linked, with its destination URL.
-3. Save and visit a post that contains one of your keywords — it should now appear as a link.
+1. Open the Theme Builder template that renders your post content — typically **Single Post**. Do not add this to an individual page.
+2. Drop the Keyword Linker widget anywhere on that template. Position is irrelevant; it renders nothing.
+3. Add a row per keyword, each with its destination URL.
+4. Decide per keyword whether to link every occurrence or cap it.
+5. Save, then visit a post containing one of your keywords and confirm the link appears.
 
 ## Good to know
 
-- **This widget needs to sit on a template that actually renders post content** — placing it on a page with no post content being displayed does nothing, since it works by intercepting WordPress's content output.
-- The first occurrence of a keyword found in a matching heading or paragraph keeps its original capitalization in the resulting link — you don't need to match the exact case when defining the keyword.
-- Links are only ever added inside `<p>` and heading tags — if your target text lives inside a list, table, or custom block markup, it won't be matched.
+- **It must sit on a template that actually renders post content.** On a page with no post content being output there is nothing to scan, so nothing happens. This is the most common reason it appears not to work.
+- **Links are only added inside `<p>` and heading tags.** If your target text lives in a list, table, or a custom block's markup, it won't be matched — move the text into a paragraph if you need it linked.
+- **Keywords are matched independently.** If two keywords overlap in the same sentence, both can be linked; there's no ordering guarantee between them, so avoid defining a keyword that is a substring of another phrase you also link.
+- Because it works on rendered output rather than stored content, removing the widget removes every generated link cleanly — your posts are never modified in the database.

docs/dotjuice-elementor-tools/widgets/markdown-widget.md

@@ -1,27 +1,80 @@
 # Markdown Widget
 
+Render a live Markdown file — a README, changelog, or documentation page — directly in your site, always showing the current version.
+
 Found in the Elementor panel under **Dotjuice → Markdown**.
 
+![The Markdown widget controls in the Elementor panel](../assets/img/markdown-widget-controls.png)
+*Screenshot: the widget selected in the editor with the **Settings** section open, showing the Markdown Source dropdown and the Markdown File URL field.*
+
 ## How it works
 
-The widget fetches the Markdown file you specify directly in the visitor's browser and converts it to HTML on the fly. Because the fetch happens in the browser, the source file needs to allow cross-origin requests — raw file URLs from GitHub (`raw.githubusercontent.com`) work well; a URL that isn't set up to allow this will fail to load, with a note in the browser's developer console.
+The widget fetches the Markdown file **on your server**, embeds the document in the page, and converts it to HTML in the visitor's browser. Fetched files are cached for 15 minutes.
+
+Because the fetch is server-side, the source does **not** need to permit cross-origin requests. Raw URLs from GitHub, Gitea, or a private self-hosted server all work.
 
 ## Content settings
 
-| Setting | What it does |
-|---|---|
-| **Markdown File URL** | The direct URL to the raw Markdown file (not a formatted preview page — for GitHub, use the "Raw" file link, not the normal file view). |
+| Setting | Default | What it does |
+|---|---|---|
+| **Markdown Source** | External URL | Choose between fetching a URL or using a file from the Media Library. |
+| **Markdown File URL** | — | Direct URL to the raw Markdown file. Supports dynamic content, so the URL can come from a custom field. |
+| **Markdown File** | — | Upload a `.md` file or pick one from the Media Library. Shown when Source is set to Uploaded file. |
+
+:::caution Use the raw file URL
+For a GitHub file, click **Raw** and use that URL. The normal file-viewer page returns an HTML page rather than Markdown source, and won't render correctly. The same applies to Gitea and most other Git hosts.
+:::
 
 ## Styling
 
-| Setting | What it does |
-|---|---|
-| **Text Color** | Sets the base text color for the rendered content. |
+| Setting | Default | What it does |
+|---|---|---|
+| **Text Color** | `#000000` | Base text colour for the rendered content. |
 
-The Markdown is converted to plain semantic HTML (headings, paragraphs, lists, code blocks, links) with no additional classes — headings, code blocks, and other elements will take on whatever styling your theme already applies to those standard HTML tags. If you want the rendered Markdown to look a specific way, style it through your theme's typography settings for headings, lists, and `<pre>`/`<code>` blocks, since this widget doesn't apply its own detailed formatting beyond the base text color.
+The Markdown is converted to plain semantic HTML — headings, paragraphs, lists, code blocks, links — with no extra classes. Those elements inherit whatever styling your theme already applies to standard HTML tags. To control the appearance, style headings, lists and `<pre>`/`<code>` through your theme's typography settings; this widget doesn't impose its own formatting beyond the base text colour.
+
+## Shortcode
+
+Anywhere the widget can't go — a WooCommerce product tab, a text editor, a template — use the shortcode instead:
+
+```
+[dj_markdown url="https://example.com/changelog.md"]
+```
+
+### Pulling the URL from a custom field
+
+Rather than a fixed URL, point the shortcode at a field name and it reads that field from the post being displayed:
+
+```
+[dj_markdown acf_field="changelog_url"]
+```
+
+This is the practical way to show a different document per post or product. Add a URL field to your products, place one shortcode in a tab or template, and every product renders its own file.
+
+The field is read from ACF when installed, and falls back to a plain custom field otherwise — so it works either way. ACF **URL**, **Text**, **Link** and **File** field types are all handled.
+
+![A per-product changelog rendered inside a product tab](../assets/img/markdown-widget-product-tab.png)
+*Screenshot: a product page with a "Changelog" tab open, showing a rendered Markdown changelog pulled from that product's own field.*
+
+### All attributes
+
+| Attribute | What it does |
+|---|---|
+| `url` | The Markdown URL to fetch. Takes precedence if both are given. |
+| `acf_field` | Name of a field holding the URL. Also accepts `acf-field` or `field`. |
+| `post_id` | Read the field from this post instead of the one being displayed. |
+| `cache` | Cache lifetime in seconds. Use `cache="0"` to always fetch fresh. |
+| `class` | Extra CSS class on the container, for styling. |
+
+`[dj-markdown]` works as an alias if you prefer the hyphen.
+
+:::tip Pairing it with product tabs
+The Pro plugin's [Woo Custom Product Tabs](../../dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md) runs shortcodes in its custom tab content, which is what makes the per-product changelog pattern above work.
+:::
 
 ## Good to know
 
-- **Use the raw file URL, not a formatted view.** For a GitHub file, click "Raw" on the file page and use that URL — the normal GitHub file-viewer page returns an HTML page, not the Markdown source, and won't render correctly.
-- The content loads via JavaScript after the page loads, so it won't appear in "view source" — this is expected and doesn't affect what visitors see.
-- If nothing appears, check your browser's developer console: the two most common causes are an incorrect URL (view page instead of raw file) or the source not allowing cross-origin requests from your domain.
+- **Only http:// and https:// URLs are accepted.** Other schemes are rejected, so a Markdown file must be reachable over the web — a local file path won't work.
+- **The rendered HTML is produced by JavaScript** after the page loads, so it won't appear in "view source". This is expected and doesn't affect what visitors see.
+- **If nothing appears and you're logged in as an editor or administrator**, the widget and shortcode both print the reason directly on the page. Visitors never see those messages — they get an HTML comment instead.
+- **Edits to a source file take up to 15 minutes to show** because of the cache. Add `cache="0"` to the shortcode while you're setting things up, then remove it.

docs/dotjuice-elementor-tools/widgets/screenshot-capture.md

@@ -1,40 +1,68 @@
 # Screenshot Capture
 
+Live screenshots of any website, captured through the Screenshot Machine API and cached in your Media Library.
+
 Found in the Elementor panel under **Dotjuice → Screenshot Capture**.
 
+![The Screenshot Capture widget's capture settings](../assets/img/screenshot-capture-controls.png)
+*Screenshot: the widget selected in the editor showing the **Capture settings** section — URL field, Refresh button, Full Page toggle, Device, Zoom and Delay controls.*
+
 ## Before you start: set up your API key
 
-This widget uses the Screenshot Machine API to capture screenshots, which requires a free or paid API key from their service. Go to **Dotjuice → Screenshot API** in your WordPress admin and enter your key — the widget won't display anything until this is done. See [Screenshot API Settings](../screenshot-api-settings.md) for full setup details.
+This widget calls the Screenshot Machine API, which needs an API key. Go to **Dotjuice → Integrations** in your WordPress admin and enter your key on the Screenshot API tab. **The widget renders nothing until this is done.** Full instructions are in [Screenshot API Settings](../screenshot-api-settings.md).
 
-## Content settings
+## How it works
+
+When a visitor loads a page containing an uncached screenshot, the plugin requests a capture from the API, saves the resulting image into your Media Library, and serves it from there afterwards. Later visitors get the stored image with no API call at all.
+
+This means two things worth planning around:
+
+- **Captures cost API calls.** Your key has a quota; each fresh capture spends one.
+- **The first visitor to an uncached screenshot waits for it.** The capture happens during their page load.
+
+The editor deliberately never triggers an automatic capture while you design — it shows a placeholder instead, so building a page doesn't burn through your quota. Use the **Refresh Screenshot** button when you actually want an image.
+
+## Capture settings
 
 | Setting | Default | What it does |
 |---|---|---|
-| **URL** | — | The web address to screenshot. |
-| **Refresh Screenshot** button | — | Editor only. Forces a brand-new capture immediately, bypassing the cache — use this after the target page has changed. |
-| **Full Page** | Off | Captures the entire scrollable page rather than just the visible viewport. |
-| **Cache Limit (days)** | 0 | How many days a captured screenshot stays cached before it's automatically re-captured on a visitor's page load. `0` means it's captured once and never automatically refreshed — use the Refresh button or clear the cache manually (see below) to update it. |
-| **Device** | Desktop | Desktop, Tablet, or Phone — captures at that device's typical screen dimensions. |
-| **Zoom** | 100% | Zoom level applied during capture, from 50% to 200%. |
-| **Click Element** | Empty | A CSS selector (or comma-separated list) to click before the screenshot is taken — useful for dismissing a cookie banner or opening a menu first. |
-| **Selector** | Empty | Crop the capture to a specific element on the target page, given as a CSS selector. |
-| **Delay (ms)** | 3000 | How long to wait after the page loads before capturing — increase this for pages with animations or content that loads in after the initial page load. |
+| **Website URL** | — | The address to capture. |
+| **Refresh Screenshot** | — | Editor only. Forces a fresh capture immediately, bypassing the cache. Use after the target page changes. |
+| **Full Page Screenshot** | Off | Captures the whole scrollable page rather than just the visible viewport. |
+| **Cache Limit** | 0 | Days a capture stays cached before being retaken automatically. `0` means capture once and never auto-refresh — you refresh manually. |
+| **Device Type** | Desktop | Desktop, Tablet or Phone. Captures at that device's typical dimensions. |
+| **Zoom (%)** | 100 | Zoom applied during capture, 50–200%. |
+| **Click Element (CSS Selector)** | Empty | A selector (or comma-separated list) clicked before capturing — for dismissing a cookie banner or opening a menu first. |
+| **Selector (CSS)** | Empty | Crop the capture to one element on the target page instead of the whole viewport. |
+| **Delay (ms)** | 3000 | How long to wait after load before capturing. Increase for pages with animations or late-loading content. |
 
-## Display settings (Style tab)
+:::tip Getting a clean capture of a site with a cookie banner
+Put the banner's accept-button selector into **Click Element**, and raise **Delay** enough for the banner's dismiss animation to finish. A 3000ms delay with no click usually still catches the banner mid-page.
+:::
 
-- **Width / Height** — the maximum size of the screenshot display area.
-- **Website Link** — if set, clicking the screenshot goes to this URL instead of the page that was captured.
-- **Show Lightbox** — opens the screenshot in a lightbox on click (only applies if Website Link is empty). Multiple Screenshot Capture widgets on the same page with this enabled become one swipeable lightbox gallery together.
-- **Scroll Speed** — for full-page captures only: how fast the image auto-scrolls to reveal the whole page (lower is faster).
-- **Border**, **Box Shadow**, **CSS Filters**, and a **Transform** popover (rotate, scale, offset, opacity) are available for both the normal and hover states, exactly like Elementor's native Image widget.
+## Display settings
+
+| Setting | What it does |
+|---|---|
+| **Width / Height** | Maximum display size of the screenshot area. |
+| **Link** | If set, clicking the screenshot goes here instead of the captured page. |
+| **Display image in lightbox** | Opens the image in a lightbox on click. Only applies when **Link** is empty. Several Screenshot Capture widgets on one page with this on become a single swipeable gallery. |
+| **Scroll Speed** | Full-page captures only. Seconds to scroll one screen height on hover — lower is faster. |
+
+**Border**, **Box Shadow**, **CSS Filters** and a **Transform** popover (rotate, scale, offset X/Y, opacity) are all available for both Normal and Hover states, matching Elementor's native Image widget.
 
 ## Managing your screenshot cache
 
-On the **Dotjuice → Screenshot API** settings page, a Cache Management panel shows how many screenshots are currently cached and their total size, with a **Clear All Cached Screenshots** button to force every screenshot on your site to be re-captured on next view. Screenshots are stored in your Media Library, so clearing the cache removes them from there too.
+The **Dotjuice → Integrations** page has a Cache Management panel showing how many screenshots are cached and their total size, with a button to clear them all and force every screenshot on the site to re-capture on next view.
+
+![The screenshot cache management panel](../assets/img/screenshot-capture-cache.png)
+*Screenshot: the Cache Management panel on the Integrations page, showing the cached count, total size and the clear button.*
+
+Screenshots live in your Media Library, so clearing the cache deletes those attachments too.
 
 ## Good to know
 
-- **Every capture uses one API call**, whether triggered by a visitor's first view of an uncached page, or the editor's Refresh button. With Cache Limit set to 0 (the default), a given screenshot is only captured once — subsequent visitors see the cached version until you manually refresh it or your Cache Limit expires it.
-- **The first visitor to an uncached page waits for the live capture** to complete before the page finishes loading. If you're about to publish a page with several uncached screenshots, visit it yourself first (or use the editor's Refresh button on each one) so the cache is warm before real visitors arrive.
-- The editor never triggers an automatic capture while you're designing, specifically to avoid spending API calls while you work — you'll see a placeholder instead until you click Refresh.
-- Changing **Cache Limit**, **Delay**, **Click Element**, or **Selector** on an already-cached screenshot won't take effect until you use the Refresh button — these settings affect how a new capture is taken, not the one already cached.
+- **Every capture costs one API call** — whether triggered by a visitor hitting an uncached page or by the editor's Refresh button. With Cache Limit at 0, each screenshot is captured once and then reused indefinitely.
+- **Warm the cache before launch.** If you're publishing a page with several uncached screenshots, visit it yourself first, or hit Refresh on each widget in the editor, so real visitors don't absorb the capture wait.
+- **Changing Cache Limit, Delay, Click Element or Selector does nothing to an already-cached image.** Those settings describe how a *new* capture is taken. Hit Refresh to apply them.
+- If a screenshot never appears, check the API key first — an unset or exhausted key is by far the most common cause.

docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md

@@ -1,31 +1,56 @@
 # Woo Add to Cart Transform
 
+Rebuild WooCommerce's variation dropdowns as clickable buttons, and style the product form to match your design.
+
 Found in the Elementor panel under **Dotjuice → Woo Add To Cart transform**. Requires WooCommerce.
 
+![The Woo Add To Cart transform controls](../assets/img/woo-add-to-cart-controls.png)
+*Screenshot: the widget selected in the editor showing the **Variation buttons** section — Swap to Buttons, Show Colour Swatches, Hide Labels and Button Spacing.*
+
 ## How it works
 
-Place this widget on your single product template (typically inside your Elementor Theme Builder's Single Product template, near where the product form appears). It finds WooCommerce's native variation `<select>` dropdowns on that page and converts them into a row of clickable buttons.
+Place this widget on your Single Product template, near where the product form appears. It finds WooCommerce's native variation `<select>` dropdowns on the page and converts each into a row of clickable buttons.
+
+Shoppers pick "Large" by clicking it rather than opening a dropdown and scrolling — fewer taps on mobile, and every option is visible at a glance.
+
+![Variation buttons on a product page](../assets/img/woo-add-to-cart-frontend.png)
+*Screenshot: a live product page showing size and colour options rendered as button rows instead of dropdowns, with one option selected.*
 
 ## Content settings
 
 | Setting | Default | What it does |
 |---|---|---|
-| **Swap to Buttons** | Off | Turns on the dropdown-to-button conversion. Leave this off if you want to keep native WooCommerce dropdowns but still use the price/description styling controls below. |
-| **Show Colour Swatches** | Off | **Pro feature.** In the free version, this setting has no visible effect — buttons always display as text. Colour swatches (each button showing its actual colour) require [Dotjuice Elementor Tools Pro](../../../../dotjuice-elementor-tools-pro/documentation/marketing/overview.md). |
-| **Hide Labels** | Off | Hides the attribute name label (e.g. "Colour", "Size") next to each button group. |
-| **Button Spacing** | 10px | Spacing between buttons within a group. |
+| **Swap to Buttons** | Off | Turns on the dropdown-to-button conversion. Leave it off to keep native dropdowns while still using the price and description styling below. |
+| **Show Colour Swatches** | Off | **Pro feature.** No visible effect in the free version — buttons always render as text. See below. |
+| **Hide Labels** | Off | Hides the attribute name ("Colour", "Size") beside each button group. |
+| **Button Spacing** | 10px | Space between buttons within a group. |
 
 ## Styling
 
-- **Buttons** — Normal and Selected states, each with text colour, background colour, typography, border, box shadow, and padding, plus a shared border radius.
-- **Text** — typography and colour for the product price and short description.
-- **Swatch** — sizing, padding, and border controls for colour swatches (only visible in the Pro version, where swatches actually render).
+| Section | What it covers |
+|---|---|
+| **Buttons** | Normal and Selected states — text colour, background, typography, border, box shadow and padding, plus a shared border radius. |
+| **Text** | Typography and colour for the product price and short description. |
+| **Swatch** | Size, padding and border for colour swatches. Only meaningful in Pro, where swatches actually render. |
+
+Style the **Selected** state distinctly — it's the only feedback a shopper gets that their choice registered.
 
 ## Setting up colour swatches (Pro)
 
-Even in the free version, you can pre-configure your swatch colours ready for when you upgrade: go to **Dotjuice → WooCommerce Hacks → Attribute Colours** and assign a colour to each attribute term (e.g. Red, Blue, Green). See [Product Attribute Colours](../product-attribute-colours.md) for the full guide. Once Pro is active and "Show Colour Swatches" is enabled, these assigned colours display automatically.
+You can pre-configure swatch colours in the free version, ready for an upgrade. Go to **Dotjuice → WooCommerce Hacks → Attribute Colours** and assign a colour to each attribute term — see [Product Attribute Colours](../product-attribute-colours.md).
+
+Once [Pro](../../dotjuice-elementor-tools-pro/getting-started.md) is active and **Show Colour Swatches** is on, those colours render automatically. Terms sharing a hex value merge into one swatch.
 
 ## Good to know
 
-- **Two WooCommerce-wide behaviours are always active once this plugin and WooCommerce are both installed**, regardless of whether you've placed this widget on any page: WooCommerce's default "Clear" reset-selection link is replaced with this widget's version, and per-variation pricing is always shown (rather than only appearing when variations have different prices). These are intentional store-wide improvements, not something you need to configure per page.
-- Because the button styling targets WooCommerce's variation markup directly rather than being scoped to just this widget, if a page shows more than one product form (for example, a quick-view popup alongside the main product), the same button styling applies to all of them.
+:::caution Two behaviours apply store-wide, with or without this widget
+Once this plugin and WooCommerce are both active, these happen everywhere regardless of whether you've placed the widget on any page:
+
+- WooCommerce's default **"Clear" reset-selection link** is replaced with this plugin's version.
+- **Per-variation pricing is always shown**, rather than appearing only when variations differ in price.
+
+These are deliberate store-wide improvements, not per-page settings. If you're wondering why a product form changed on a template where you never added the widget, this is why.
+:::
+
+- **Button styling targets WooCommerce's variation markup directly** rather than being scoped to this widget instance. If a page shows more than one product form — a quick-view popup alongside the main product, say — the same styling applies to all of them.
+- The conversion runs against whatever dropdowns exist at page load. A theme or plugin that injects extra variation fields later won't have those converted.

docs/dotjuice-elementor-tools/widgets/woo-categories-transform.md

@@ -1,36 +1,61 @@
 # Woo Categories Transform
 
+Turn WooCommerce's plain category tiles into styled, animated cards with overlay text and hover effects.
+
 Found in the Elementor panel under **Dotjuice → Woo Categories Transform**. Requires WooCommerce.
 
+![A styled category grid on the shop page](../assets/img/woo-categories-transform-frontend.png)
+*Screenshot: a shop page showing category tiles with overlaid titles on a frosted background, one tile mid-hover with its image scaled.*
+
 ## How it works
 
-Place this widget on any page that shows WooCommerce's product category tiles — typically your Shop page when it's set to display subcategories. It restructures the tile markup into styleable wrapper sections and applies the styling you configure below to every category tile on that page.
+Place this widget on any page that displays WooCommerce's product category tiles — usually the Shop page when it's set to show subcategories. It restructures the tile markup into styleable wrapper sections, then applies your styling to every category tile on that page.
 
-This widget has no Content tab — every setting lives under Style.
+**This widget has no Content tab.** Every setting lives under Style, because it isn't producing content of its own — it's restyling markup WooCommerce already outputs.
 
 ## Box styling
 
-Border style, colour, width, radius, background colour, and padding for the overall category tile.
+Border style, colour, width and radius, background colour, and padding for the tile as a whole.
 
 ## Image styling
 
-- **Overflow** — controls whether hover transforms are clipped to the image area or allowed to spill outside it.
-- Border, radius, and — for Normal and Hover states separately — a Transform popover (rotate, scale, offset, opacity), Box Shadow, and CSS Filters.
+| Setting | What it does |
+|---|---|
+| **Overflow** | Whether hover transforms are clipped to the image area or allowed to spill outside it. Set to hidden for a contained zoom; visible lets an image grow past its frame. |
+| **Border / Radius** | Standard border controls on the image itself. |
+| **Transform** (Normal & Hover) | Rotate, scale, offset X/Y and opacity — a popover per state. |
+| **Box Shadow** (Normal & Hover) | Separate shadows per state. |
+| **CSS Filters** (Normal & Hover) | Blur, brightness, contrast, saturation and hue. |
+
+Because Normal and Hover are configured separately, the transition between them is what creates the animation — set scale to 1 on Normal and 1.05 on Hover for a standard zoom-in.
 
 ## Content styling
 
-- **Hide Product Count** — the product count badge is hidden by default; turn this off if you'd like the count shown.
-- **Position** — Relative (sits naturally below the image) or Absolute (overlays directly on top of the image, positioned at the bottom).
-- Font colour, background colour, an optional background blur effect (for a frosted-glass look behind overlaid text), padding, border, and box shadow.
+![The Content styling section of the widget](../assets/img/woo-categories-transform-controls.png)
+*Screenshot: the widget's Content styling section showing Hide Product Count, the Position selector, and the background blur control.*
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Hide Product Count** | On | The count badge is hidden by default. Switch this off to show it. |
+| **Position** | Relative | **Relative** sits the text naturally below the image. **Absolute** overlays it on the image, anchored to the bottom. |
+| **Font / Background colour** | — | Colours for the title text and the band behind it. |
+| **Background blur** | — | Frosted-glass effect behind overlaid text. Most effective with a semi-transparent background colour. |
+| **Padding / Border / Box shadow** | — | Standard spacing and framing for the text area. |
 
 ## Setting it up
 
-1. Add the widget to your Shop page (or wherever your category tiles are displayed).
-2. For an overlay-style card, set Content Position to Absolute and add a background colour with some transparency, or enable the blur effect for a frosted look.
-3. Configure hover effects under Image styling for a polished interactive feel.
+1. Add the widget to your Shop page, or wherever category tiles are displayed.
+2. For an overlay card, set **Position** to Absolute and give the background a semi-transparent colour — then add blur for a frosted look.
+3. Configure the Normal and Hover transforms under Image styling to create the hover animation.
+4. Preview on the front end; the editor may not show real category tiles depending on how your shop page is configured.
 
 ## Good to know
 
-- **Two things happen automatically once this plugin and WooCommerce are both active**: the tile markup restructuring (extra wrapper elements around each category tile) happens site-wide regardless of whether this widget is placed anywhere, but the actual **styling** only applies once you've placed the widget on the page showing those tiles.
-- Styling isn't scoped to a single widget instance — placing the widget once styles every category tile shown on that page.
-- The product count badge is **hidden by default** — if you expect to see a count and it's missing, check the "Hide Product Count" setting.
+:::note Markup changes are store-wide; styling is not
+Once this plugin and WooCommerce are both active, the **tile markup restructuring** (extra wrapper elements around each tile) happens site-wide whether or not you've placed this widget. The **styling** only applies on pages where the widget is present.
+
+This split is intentional — it means the markup is consistent everywhere, so your CSS or a child theme can rely on it even on pages without the widget.
+:::
+
+- **Styling is not scoped per instance.** Placing the widget once styles every category tile on that page; adding a second instance won't give you two different looks on the same page.
+- **The product count is hidden by default.** If you expected a count and it's missing, check **Hide Product Count** rather than assuming the theme removed it.

docs/dotjuice-elementor-tools/widgets/woo-my-account-transform.md

@@ -1,23 +1,39 @@
 # Woo My Account Transform
 
+Bring WooCommerce's My Account area in line with the rest of your design.
+
 Found in the Elementor panel under **Dotjuice → Woo My Account Transform**. Requires WooCommerce.
 
+![The My Account area with custom button and link styling](../assets/img/woo-my-account-transform.png)
+*Screenshot: a logged-in My Account page — Orders view — showing styled action buttons and order-table links matching the site's branding.*
+
 ## How it works
 
-Place this widget on your My Account page template (typically inside your Elementor Theme Builder's My Account template). It detects buttons and links within the account content area and applies the styling you configure below.
+Place this widget on your My Account page template, typically inside Elementor's Theme Builder My Account template. It detects the buttons and links within the account content area and applies your styling to them.
+
+The My Account area is normally one of the hardest parts of a WooCommerce store to style, because it's rendered by WooCommerce templates rather than built in Elementor. This widget bridges that gap without you needing to override any templates.
 
 ## Styling
 
-- **Button Style** — Normal and Hover states, each with text colour, background colour, border, border radius, and box shadow, plus shared typography and padding. Applies to account action buttons (e.g. form submit buttons, "Pay", "Cancel").
-- **Link Style** — typography, plus Normal and Hover text colour, applied to order-table links: download links, product name links, and order number links.
+| Section | Applies to | Controls |
+|---|---|---|
+| **Button Style** | Account action buttons — form submits, "Pay", "Cancel", "View order" | Normal and Hover states with text colour, background, border, radius and box shadow, plus shared typography and padding |
+| **Link Style** | Order-table links — downloads, product names, order numbers | Typography, plus Normal and Hover text colour |
 
 ## Setting it up
 
-1. Add the widget anywhere inside your My Account page template.
-2. Configure your button and link colours to match your site's branding.
-3. Visit the My Account page while logged in (as a real customer account, since this only applies within the actual account content) to check the styling.
+1. Add the widget anywhere inside your My Account page template. Position doesn't matter — it styles the whole area, not the spot where it sits.
+2. Set your button and link colours to match your branding.
+3. **Preview on the front end while logged in as a real customer account.** This is the only reliable way to check it.
 
 ## Good to know
 
-- **Styling applies across the whole My Account area on that page, not just near the widget** — you only need to place this widget once on your My Account template for it to take effect everywhere within it.
-- You won't see live account content while editing in Elementor — the editor shows a placeholder instead, since there's no real logged-in account context inside the editor. Preview your changes by viewing the actual My Account page on the front end while logged in.
+:::caution The editor can't show you real account content
+Elementor has no logged-in customer context, so the editor shows a placeholder rather than live orders, addresses or downloads. Style with the front end open in another tab and refresh as you go.
+
+A test customer account with at least one completed order gives you something realistic to style against — an empty account shows almost none of the elements these controls target.
+:::
+
+- **Styling applies across the whole My Account area on that page, not just near the widget.** Place it once per template; adding more instances does nothing extra.
+- Buttons and links inside the account content are targeted, but the account **navigation menu** is a separate element — style that with Elementor's own controls or your theme.
+- If your theme heavily overrides WooCommerce's account templates with custom markup, some elements may fall outside what this widget targets.

docs/dotjuice-elementor-tools/widgets/woo-page-numbers.md

@@ -1,29 +1,51 @@
 # Woo Page Numbers
 
+Styleable product pagination that co-operates with AJAX filtering.
+
 Found in the Elementor panel under **Dotjuice → Woo Page Numbers**. Requires WooCommerce.
 
+![Styled product pagination on a shop archive](../assets/img/woo-page-numbers.png)
+*Screenshot: a shop archive footer showing the pagination with the current page highlighted in the site's accent colour.*
+
 ## How it works
 
-Place this widget on your Shop page or any product archive/category template, where it will show. It wraps WooCommerce's built-in pagination and applies the styling you configure.
+Place this widget on your Shop page or any product archive or category template. It wraps WooCommerce's built-in pagination and applies your styling.
 
-This widget only shows real pagination when there's more than one page of results to paginate through — on a page with too few products to need pagination, it will render an empty space.
+It only renders real pagination when there is more than one page of results. On an archive with too few products to paginate, it renders empty space.
 
 ## Styling
 
-There's no Content tab — every setting lives under Style:
+This widget has no Content tab — everything lives under Style.
 
-- **Alignment** — left, centre, or right.
-- **Typography** — font styling shared across all pagination links.
-- **Normal / Hover** — text and background colour for regular page number links.
-- **Active** — text and background colour for the current page indicator (styled separately, since it's not a clickable link).
-- **Border** and **Padding** — spacing and border styling for each page number.
+| Setting | What it does |
+|---|---|
+| **Alignment** | Left, centre or right. |
+| **Typography** | Shared across all pagination links. |
+| **Normal / Hover** | Text and background colour for regular page-number links. |
+| **Active** | Text and background colour for the current page. Styled separately because it isn't a clickable link. |
+| **Border** | Border style, colour, width and radius per page number. |
+| **Padding** | Space inside each page number, which controls the tap-target size. |
+
+:::tip Mind the tap target on mobile
+Padding here decides how big each number is to tap. Anything under about 44px square gets fiddly on a phone — worth checking at a mobile breakpoint before you ship.
+:::
 
 ## Setting it up
 
 1. Add the widget to your Shop page or a product category archive template.
-2. Style the Normal, Hover, and Active states to match your site.
-3. Preview on the live site with enough products to trigger real pagination — the Elementor editor shows a fixed example (pages 1–4) purely so you can preview your styling, which won't match your site's real page count.
+2. Style the Normal, Hover and Active states so the current page is clearly distinct.
+3. **Preview on the live site with enough products to trigger real pagination.** The editor shows a fixed 1–4 example purely so you have something to style against — it won't match your real page count.
+
+## Works with the AJAX Product Filter
+
+If a Pro [Woo Product Filter](../../dotjuice-elementor-tools-pro/widgets/woo-product-filter.md) is on the same page with AJAX enabled, clicking a page number loads that page's products in place — no full reload — while keeping the shopper's active filters applied.
+
+The browser URL updates to the normal pretty archive form, e.g. `/t-shirts/page/2/`, so paged views stay shareable and bookmarkable and the back/forward buttons work as expected. On sites using plain permalinks it falls back to `?paged=2`.
+
+No extra configuration is needed — place both widgets on the page and they find each other.
 
 ## Good to know
 
-- **The Elementor editor always shows a sample 4-page pagination** so you have something to style against — this is a preview aid only, not a reflection of your real page count. Check the actual front end to see your real pagination.
+- **The editor always shows a sample four-page pagination.** It's a styling aid, not a reflection of your catalogue. Always confirm on the front end.
+- Because it wraps WooCommerce's native pagination, it respects your **Products per page** setting from WooCommerce and your theme — change the page count there, not here.
+- On an archive with a single page of results the widget outputs nothing visible, which can leave a gap if you've given its container padding or a margin.

docs/dotjuice-elementor-tools/widgets/woo-products-transform.md

@@ -0,0 +1,102 @@
+# Woo Products Transform
+
+Add hover effects, image rollovers and colour swatches to an Elementor Pro product grid.
+
+Found in the Elementor panel under **Dotjuice → Woo Products Transform**. Requires WooCommerce and Elementor Pro's Products widget.
+
+![A product grid with hover effects applied](../assets/img/woo-products-transform-frontend.png)
+*Screenshot: a product grid on the shop page, one tile mid-hover showing its image scaled with the content overlay visible.*
+
+## How it works
+
+Drop this widget onto the same page or template as an Elementor Pro **Products** widget — your Shop archive, a category template, or any page showing a product loop. It restructures each product into styleable wrapper sections (an image wrapper and a content wrapper) and applies your effects to **every product in that loop**.
+
+**It does not render a grid of its own.** It transforms the grid rendered by Elementor Pro's Products widget, so the two are always used together: the Products widget for the grid, this one for styling and behaviour.
+
+There's no Content tab — everything lives under **Style**, in the four sections below. Most settings preview live in the editor; hover-based effects are best confirmed on the front end.
+
+![The Woo Products Transform style sections](../assets/img/woo-products-transform-controls.png)
+*Screenshot: the widget selected in the editor with the **Image transform** section open, showing the Normal/Hover tabs and the transform popover.*
+
+## Image transform
+
+| Setting | What it does |
+|---|---|
+| **Disable Default Add to Cart** | Removes WooCommerce's loop "Add to cart" button — useful for a cleaner grid, or if you add your own. |
+| **Overflow** | Overflow for the image wrapper. Set **Hidden** to clip a scaled image to its frame. |
+| **Border** (style, colour, width, radius) | A border around the product image. |
+
+Below those, **Normal** and **Hover** tabs expose the same set of effects, so you animate between a resting state and a hover state:
+
+- **Transform** — a popover with Rotate, Scale and Offset X/Y. A subtle scale on Hover gives the standard zoom.
+- **Opacity** — fade the image in or out.
+- **CSS Filters** — blur, brightness, contrast, saturation, hue.
+- **Box Shadow** — per state.
+
+At the top of this section sits **Enable Image Rollover** (Pro). Switching it on **hides and disables** the transform, opacity, filter and shadow controls above, because rollover and hover transforms are mutually exclusive — you can't scale an image and swap it for another at the same time.
+
+## Image Rollover (Pro)
+
+Instead of transforming the image on hover, show a **second image** — the same garment on a different model, or a front/back view.
+
+![A product tile mid-rollover showing the second image](../assets/img/woo-products-transform-rollover.png)
+*Screenshot: two product tiles side by side, one at rest showing the featured image and one hovered showing its rollover image.*
+
+**Where the second image comes from,** per product, in priority order:
+
+1. A dedicated **Rollover Image**, set on the product edit screen in the **Rollover Image (Hover)** box.
+2. Otherwise the product's **first gallery image**, used automatically as a fallback.
+
+Tick **Disable rollover for this product** on any product to opt it out.
+
+| Setting | What it does |
+|---|---|
+| **Effect** | How the second image enters — Fade, Zoom In/Out, or Slide Up/Down/Left/Right. |
+| **Duration (ms)** | Length of the crossfade or slide. |
+| **Easing** | The transition curve — Ease, Linear, the Ins/Outs, plus Smooth and Back/Overshoot. |
+| **Disable Gallery Fallback** | Only roll over products with an explicit Rollover Image. Products relying on the gallery keep their featured image untouched. |
+
+Second images use native lazy loading. On touch devices, where there's no hover, products simply show their featured image.
+
+## Variation swatches (Pro)
+
+For **variable** products, show clickable colour swatches beneath each product in the loop. Clicking one swaps the product image to that variation's image, letting shoppers preview colours without opening the product.
+
+| Setting | What it does |
+|---|---|
+| **Show colour swatches** | Master toggle, off by default. |
+| **Swatch taxonomy** | Which attribute drives the swatches, e.g. `Colour` / `pa_color`. |
+| **Swatch Gap / Alignment** | Spacing and horizontal alignment of the swatch row. |
+| **Normal / Hover / Active** | Swatch Size, Border and Border Radius per state. Active is the currently selected swatch. |
+
+Swatch colours come from the attribute term colours you set under [Product Attribute Colours](../product-attribute-colours.md).
+
+## Content transform
+
+Styles the block holding the title and price, plus a few content tweaks.
+
+| Setting | What it does |
+|---|---|
+| **Change title tag** | Output the product title as H2–H6 instead of the default. A **Title heading tag** dropdown appears when on. |
+| **Hide Star Ratings** / **Hide Prices** | Remove those elements from the loop. |
+| **Content wrapper styling** | Background colour, **Blur** (backdrop blur, for an overlay sitting over the image), padding, border and box shadow. |
+
+## Box Transform
+
+**Show Overlay** sets the overflow of each product tile. Set it to Hidden to clip child content — a scaled image, or an absolutely-positioned content overlay — to the tile boundary.
+
+## Setting it up
+
+1. Add the widget to the same template or page as your Elementor Pro Products widget.
+2. Choose between hover **image transforms** and **Image Rollover** — you can only use one.
+3. For transforms: set the resting state on **Normal**, the effect on **Hover**.
+4. For rollover: set a Rollover Image on the products that need one (or rely on the gallery fallback), then pick Effect, Duration and Easing.
+5. For variable products, enable **Show colour swatches** and pick the driving attribute.
+6. Use **Content transform** for the title tag and to hide price or rating, and **Box Transform** to clip overflow.
+
+## Good to know
+
+- **It only has a visible effect on pages that actually render an Elementor Pro Products loop.** On a page without one, the widget does nothing.
+- **Rollover, swatches and transforms all keep working on products loaded by the Dotjuice AJAX product filter**, so filtered results behave identically to the first page load.
+- **The Pro-only controls disappear when Pro is deactivated**, replaced by a short "available in Pro" note. The rest of the widget carries on working.
+- Set **Overflow** to Hidden before spending time on a scale effect — without it, a scaled image spills over neighbouring tiles and the grid looks broken.

docs/dotjuice-elementor-tools/widgets/woo-taxonomy-list.md

@@ -1,61 +1,90 @@
 # Woo Taxonomy List
 
+Cascading term lists from any taxonomy — a "Shop by Category" block, or a plain list of blog categories.
+
 Found in the Elementor panel under **Dotjuice → Woo Taxonomy List**.
 
-**Note:** despite the "Woo" name, this widget works with any public taxonomy on your site — product categories, blog categories, tags, or a custom taxonomy — not just WooCommerce. It currently only appears in the widgets panel when WooCommerce is active; if you'd like to use it purely for blog categories on a site without WooCommerce, get in touch with support.
+![A grouped category list on the front end](../assets/img/woo-taxonomy-list-frontend.png)
+*Screenshot: a sidebar "Shop by Category" block showing two parent terms as headings with their child terms listed and counts in brackets.*
+
+:::note Not just for WooCommerce
+Despite the name, this widget works with **any public taxonomy** — product categories, blog categories, tags, or a custom taxonomy. It only appears in the widgets panel when WooCommerce is active, so on a site without WooCommerce it isn't available even for blog categories. Get in touch with support if you need it standalone.
+:::
 
 ## Two display modes
 
-**Flat mode** lists every term in the chosen taxonomy in one simple list — good for a straightforward "browse all categories" block.
+**Hierarchical mode** (the default) lets you pick specific parent terms and shows each with its children nested beneath — a "Shop by Category" block grouping related subcategories under their parent.
 
-**Hierarchical mode** (the default) lets you choose specific parent terms, and displays each one with its child terms nested beneath — good for a "Shop by Category" style block where you want to group related subcategories under their parent.
+**Flat mode** lists every term in the taxonomy in one simple list — a straightforward "browse all categories" block.
 
 ## Content settings — Widget Heading
 
 | Setting | What it does |
 |---|---|
-| **Heading Text** | An optional title shown above the list. |
-| **Heading URL** | If set (and Heading Text is filled in), makes the heading a clickable link. |
-| **Heading Tag** | The HTML tag used for the heading (H2–H6, or a plain div), for correct document structure. |
+| **Heading Text** | Optional title above the list. |
+| **Heading URL** | Makes the heading a link. Only applies when Heading Text is filled in. |
+| **Heading Tag** | H2–H6 or a plain div, so the page keeps a sensible document outline. |
 
 ## Content settings — List Settings
 
+![The List Settings section with the taxonomy and parent term pickers](../assets/img/woo-taxonomy-list-controls.png)
+*Screenshot: the widget's **List Settings** section showing the Taxonomy dropdown, the Parent Terms multi-select populated with terms, and the Max Depth control.*
+
 | Setting | Default | What it does |
 |---|---|---|
-| **Taxonomy** | Product categories | Which taxonomy to pull terms from — every public taxonomy registered on your site is available here. |
-| **Show All Terms (Flat)** | Off | Switches to flat mode (see above). |
-| **Parent Terms** | — | Hierarchical mode only. Choose which parent term(s) to display, each with its children listed beneath. |
-| **Show Parent Term** | On | Hierarchical mode only. Shows the parent term itself as a clickable heading above its children. |
-| **Max Depth** | 1 level | Hierarchical mode only. How many levels of nested children to show beneath each parent — 1, 2, 3, or all levels. |
-| **Hide Empty Terms** | On | Excludes terms with no posts or products assigned to them. |
-| **Order By** | Name | Name, Count, Slug, or Term ID. |
+| **Taxonomy** | Product categories | Which taxonomy to pull terms from. Every public taxonomy on your site is listed. |
+| **Show All Terms (Flat)** | Off | Switches to flat mode. |
+| **Parent Terms** | — | Hierarchical only. Which parent term(s) to display, each with its children beneath. |
+| **Show Parent Term** | On | Hierarchical only. Shows the parent itself as a clickable heading above its children. |
+| **Max Depth** | 1 level | Hierarchical only. How many levels of children to show — 1, 2, 3, or all. |
+| **Hide Empty Terms** | On | Excludes terms with nothing assigned to them. |
+| **Order By** | Name | Name, Count, Slug or Term ID. |
 | **Order** | Ascending | Ascending or descending. |
 
+:::tip The Parent Terms list follows the Taxonomy dropdown
+Change **Taxonomy** and the **Parent Terms** picker repopulates with terms from the new taxonomy. This cascade only runs inside the Elementor editor — so if you're scripting or importing widget settings, set both fields explicitly rather than expecting the cascade to fill one in.
+:::
+
 ## Content settings — Display
 
 | Setting | What it does |
 |---|---|
-| **Show Term Count** | Adds a post/product count in brackets after each term name. |
-| **List Icon** | An optional icon (as a CSS icon class, e.g. from Font Awesome) shown before each term link. |
+| **Show Term Count** | Adds the post or product count in brackets after each term. |
+| **List Icon** | An optional icon before each term link, given as a CSS icon class (e.g. Font Awesome). |
 
 ## Styling
 
-Extensive styling is available, organised into: **Heading** (typography, colour, spacing), **List Container** (padding, background, border, shadow), **Parent Items** and **Parent Link Text** (hierarchical mode only), **List Items** (marker style — none, disc, circle, square, numbers, or letters — spacing, indentation, background, and hover background), **Link Text** (typography, colour, hover underline), and **List Icon** (size, colour, spacing) if you've set one.
+Grouped into sections:
+
+| Section | Covers |
+|---|---|
+| **Heading** | Typography, colour, spacing |
+| **List Container** | Padding, background, border, shadow |
+| **Parent Items** / **Parent Link Text** | Hierarchical mode only — the parent row and its link text |
+| **List Items** | Marker style (none, disc, circle, square, numbers, letters), spacing, indentation, background, hover background |
+| **Link Text** | Typography, colour, hover underline |
+| **List Icon** | Size, colour, spacing — only relevant if you've set an icon |
 
 ## Setting it up
 
-**For a flat list** (e.g. "all blog categories"):
-1. Choose your Taxonomy.
+**A flat list**, e.g. all blog categories:
+
+1. Choose your **Taxonomy**.
 2. Turn on **Show All Terms (Flat)**.
 3. Style as needed.
 
-**For a grouped list** (e.g. "Shop by Category" with subcategories):
-1. Choose your Taxonomy.
-2. Leave Flat mode off, and select your parent term(s) in **Parent Terms**.
-3. Set **Max Depth** to however many levels of children you want shown.
+**A grouped list**, e.g. "Shop by Category" with subcategories:
+
+1. Choose your **Taxonomy**.
+2. Leave flat mode off and select your **Parent Terms**.
+3. Set **Max Depth** to how many levels of children you want.
 4. Style as needed.
 
 ## Good to know
 
-- **If your configuration doesn't resolve to any terms** (for example, hierarchical mode with no parent terms selected yet), the widget shows a helpful explanatory message while you're editing in Elementor — but shows nothing at all on the live front end. Always double-check your configuration is complete before publishing.
-- The **Parent Terms** picker updates automatically to show terms from whichever taxonomy you've selected, but this live update only works while you're inside the Elementor editor.
+:::caution An incomplete configuration renders nothing on the front end
+If your settings don't resolve to any terms — hierarchical mode with no parent terms selected yet is the usual case — the editor shows an explanatory message, but the live site shows **nothing at all**. Confirm the configuration is complete before publishing.
+:::
+
+- **Hide Empty Terms is on by default.** A term you expect to see but which has no products assigned won't appear; switch it off if you're building the catalogue out of order.
+- Ordering applies within each level, so under a parent the children sort independently of how the parents themselves are ordered.

docs/dotjuice-elementor-tools/woocommerce-account-settings.md

@@ -2,31 +2,62 @@
 
 **Dotjuice → WooCommerce Hacks → General** (only visible with WooCommerce active)
 
+A set of targeted fixes for the WooCommerce behaviours most stores end up wanting to change — account menu clutter, post-logout destination, filtered-URL SEO, and keeping certain products out of general browsing.
+
+![The WooCommerce Hacks General tab](./assets/img/woocommerce-account-settings.png)
+*Screenshot: the WooCommerce Hacks page on the General tab, showing the toggles and the taxonomy term checklist at the bottom.*
+
 ## Settings
 
 | Setting | Default | What it does |
 |---|---|---|
-| **Hide Dashboard Tab** | Off | Removes the "Dashboard" entry from the My Account menu. |
-| **Hide Downloads Tab** | Off | Removes the "Downloads" entry from the My Account menu — useful for stores that don't sell downloadable products. |
-| **Auto Redirect to Orders** | Off | Sends customers straight to their Orders page instead of the generic Account dashboard when they visit My Account. **Requires "Hide Dashboard Tab" to also be enabled** — see below. |
-| **Redirect After Logout** | Off | Sends customers to your site's homepage after logging out, instead of WooCommerce's default behaviour. |
-| **Exclude Product Categories from Shop** | None selected | A checkbox tree of every product category on your store. Categories you check are hidden from your main Shop page and from that category's own archive page. |
+| **Hide Dashboard Tab** | Off | Removes "Dashboard" from the My Account menu. |
+| **Hide Downloads Tab** | Off | Removes "Downloads" from the My Account menu — useful when you sell nothing downloadable. |
+| **Auto Redirect to Orders** | Off | Sends customers straight to Orders instead of the account dashboard. **Requires Hide Dashboard Tab to also be on** — see below. |
+| **Redirect After Logout** | Off | Sends customers to your homepage after logging out instead of WooCommerce's default. |
+| **Canonical for Filtered URLs** | Off | SEO: points filtered shop and archive URLs at their base archive — see below. |
+| **Hide Products from Shop by Taxonomy** | None | Pick a product taxonomy (categories, tags, brands, attributes, or a custom one) and tick the terms whose products should be hidden from the Shop page and that term's archive. |
 
-## ⚠ "Auto Redirect to Orders" needs "Hide Dashboard Tab" enabled too
+## "Auto Redirect to Orders" needs "Hide Dashboard Tab" too
 
-These two settings work together — Auto Redirect to Orders only takes effect when Hide Dashboard Tab is also switched on. If you enable Auto Redirect on its own and it doesn't seem to do anything, check that Hide Dashboard Tab is enabled as well.
+:::caution
+These two work as a pair. **Auto Redirect to Orders only takes effect when Hide Dashboard Tab is also on.** If you switch on the redirect alone and nothing happens, this is why.
 
-## About excluding categories
+The reason is that the redirect sends people away from the dashboard, so leaving the dashboard link visible in the menu would produce a tab that bounces the customer elsewhere every time they click it.
+:::
 
-Excluding a category here hides its products from:
+## Canonical for Filtered URLs (SEO)
+
+If you use the Pro [Woo Product Filter](../dotjuice-elementor-tools-pro/widgets/woo-product-filter.md), shoppers generate URLs like `?product_cat=t-shirts&pa_color=blue` as they browse. Left alone, search engines can treat every filter combination as a separate near-duplicate page, spreading your ranking signals across thousands of thin variants.
+
+Switch this on and the plugin sets each page's **canonical URL** to the base archive, telling search engines which single page to index:
+
+| Situation | Canonical points to |
+|---|---|
+| A category or attribute archive, filtered further | That term's clean archive, e.g. `/t-shirts/` |
+| The shop page filtered by a single category | That category's archive, e.g. `/t-shirts/` |
+| Anything else — multiple categories, attribute-only filters | The shop page |
+
+Pagination and filter combinations all consolidate onto that one page. It works with **Yoast SEO** and **Rank Math**, whichever is active. Filter URLs continue to work normally for shoppers — this only changes the canonical tag search engines read, not what people see.
+
+Safe to leave on for any filtered store.
+
+## Hiding products by taxonomy
+
+Ticking a term here removes its products from:
 
 - Your main Shop page
-- That category's own archive page
+- That term's own archive page
 
-It does **not** hide those products from search results or from other custom product displays elsewhere on your site (like related products, or a widget built to specifically show that category). This is intentional — it's meant for keeping a category out of general browsing, not hiding it from your store entirely.
+It does **not** remove them from search results, related products, or any widget built to show that term specifically. That's deliberate: this is for keeping products out of general browsing — clearance lines, trade-only items, accessories that clutter the grid — not for hiding them from the store entirely.
+
+If you need a product genuinely hidden everywhere, use WooCommerce's own catalog visibility setting on the product instead.
 
 ## Setting it up
 
-1. Enable whichever toggles match what you want changed.
-2. If you want customers redirected straight to Orders, enable both **Hide Dashboard Tab** and **Auto Redirect to Orders** together.
-3. For category exclusions, check the categories you want hidden from your Shop page in the tree, then save.
+1. Switch on whichever toggles match what you want changed.
+2. To send customers straight to Orders, enable **Hide Dashboard Tab** and **Auto Redirect to Orders** together.
+3. On a filtered store, enable **Canonical for Filtered URLs**.
+4. To hide products, choose a taxonomy, tick the terms, and save.
+
+Changes take effect immediately — no cache clear needed unless you run full-page caching, in which case purge it so shoppers don't see stale archives.

docs/dotjuice-pagespeed/advanced.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → Advanced**
 
+![The Advanced settings tab](./assets/img/pagespeed-advanced.png)
+*Screenshot: the Advanced tab showing the Heartbeat API, XML-RPC, and WooCommerce script controls.*
+
 ## What this tab controls
 
 WordPress's Heartbeat API, XML-RPC, and WooCommerce script loading on non-shop pages.

docs/dotjuice-pagespeed/caching.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → Caching**
 
+![The Caching settings tab](./assets/img/pagespeed-caching.png)
+*Screenshot: the Caching tab showing the Enable Page Caching, Separate Cache for Mobile Devices, and Cache Expiry settings.*
+
 ## What this tab controls
 
 Full-page HTML caching: whether pages are cached at all, whether mobile and desktop get separate cached copies, whether logged-in visitors are included, and how long a cached page stays valid before it's rebuilt.

docs/dotjuice-pagespeed/cdn.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → CDN**
 
+![The CDN settings tab](./assets/img/pagespeed-cdn.png)
+*Screenshot: the CDN tab showing the CDN URL input and the Enable CDN Rewrite toggle.*
+
 ## What this tab controls
 
 Rewriting your site's stylesheet and script URLs to point at a CDN hostname instead of your own server.

docs/dotjuice-pagespeed/css-optimisation.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → CSS**
 
+![The CSS optimisation settings tab](./assets/img/pagespeed-css.png)
+*Screenshot: the CSS tab showing the Minify CSS, Combine CSS Files, and Load Combined CSS Asynchronously toggles.*
+
 ## What this tab controls
 
 Minification and combining of your site's local stylesheets, optional asynchronous loading of the combined file, and manual exclusions for stylesheets that shouldn't be touched.

docs/dotjuice-pagespeed/database.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → Database**
 
+![The Database optimisation settings tab](./assets/img/pagespeed-database.png)
+*Screenshot: the Database tab showing the manual cleanup options and the scheduled cleanup settings.*
+
 ## What this tab controls
 
 One-click and scheduled cleanup of database bloat: old post revisions, abandoned drafts, spam comments, expired cache entries, orphaned metadata, and full table optimisation.

docs/dotjuice-pagespeed/getting-started.md

@@ -2,7 +2,10 @@
 
 ## Where to find the settings
 
-After activating the plugin, go to **Dotjuice → Page speed** in your WordPress admin menu. Settings are organised into nine tabs: Caching, CSS, JavaScript, HTML, Images, Preload, CDN, Database, and Advanced.
+**Dotjuice → Page speed** in your WordPress admin menu.
+
+![The Dotjuice Page Speed admin dashboard](./assets/img/pagespeed-dashboard.png)
+*Screenshot: the main Page Speed admin page showing the tabbed settings interface with the Caching tab active and the Save Settings button in the toolbar.*
 
 Every toggle saves through a single **Save Settings** button in the top toolbar — changes aren't applied until you click it. A **Clear Cache** button sits next to it for whenever you want to force a fresh rebuild of every cached page.
 

docs/dotjuice-pagespeed/html-optimisation.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → HTML**
 
+![The HTML optimisation settings tab](./assets/img/pagespeed-html.png)
+*Screenshot: the HTML tab showing the Minify HTML Output, Remove Version Query Strings, and Disable Emoji Scripts toggles.*
+
 ## What this tab controls
 
 HTML minification, removal of unnecessary version query strings and default WordPress scripts, Google Fonts display behaviour, and DNS prefetch hints.

docs/dotjuice-pagespeed/images.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → Images**
 
+![The Images settings tab](./assets/img/pagespeed-images.png)
+*Screenshot: the Images tab showing the Lazy Load Images, Lazy Load Iframes, and Add Missing Width/Height toggles.*
+
 ## What this tab controls
 
 Lazy loading of images and iframes, and automatic width/height attributes to prevent layout shift.

docs/dotjuice-pagespeed/javascript-optimisation.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → JavaScript**
 
+![The JavaScript optimisation settings tab](./assets/img/pagespeed-javascript.png)
+*Screenshot: the JavaScript tab showing the Minify JavaScript, Combine JavaScript Files, Defer Loading, and Delay JavaScript Until Interaction toggles.*
+
 ## What this tab controls
 
 Minification and combining of local scripts, deferred loading, delayed loading until user interaction, and manual exclusions.

docs/dotjuice-pagespeed/preload.md

@@ -2,6 +2,9 @@
 
 **Dotjuice → Page speed → Preload**
 
+![The Preload settings tab](./assets/img/pagespeed-preload.png)
+*Screenshot: the Preload tab showing the Priority Image, Cache Preload After Publishing, and Font Preloading settings.*
+
 ## What this tab controls
 
 Priority loading for your most important image, automatic cache warming after publishing, font preloading, and DNS/connection hints for third-party services.

docs/dotjuice-pagespeed/troubleshooting.md

@@ -1,5 +1,8 @@
 # Troubleshooting
 
+![The troubleshooting guide and tools](./assets/img/pagespeed-troubleshooting.png)
+*Screenshot: the troubleshooting page showing the system status, cache log, and common fixes.*
+
 ## A page looks broken after enabling a setting
 
 1. Click **Clear Cache** and reload the page — a stale cached copy from before your change is the most common cause.

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/acf-frontend-form.md

@@ -1,15 +0,0 @@
-# ACF Frontend Form
-
-Let visitors edit Advanced Custom Fields content from the front end — no admin access, no wp-admin, just a form on your page.
-
-## The problem it solves
-
-Advanced Custom Fields is one of the most powerful tools in WordPress for structured content, but editing it has always meant going into wp-admin. For membership sites, directories, community-submitted content, or client self-service portals, that's a real barrier.
-
-## How it helps
-
-ACF Frontend Form renders ACF's own native form interface — the same tabs, repeaters, and field layouts you're used to from the admin edit screen — directly on any front-end page, for the post or page currently being viewed. Choose exactly which field groups are editable, and whether the post title and content are included too.
-
-## The result
-
-Genuine front-end content editing, using ACF's real, familiar form fields — not a simplified imitation.

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/woo-add-product-tab.md

@@ -1,17 +0,0 @@
-# Woo Add Product Tab
-
-Add one extra tab to your product page's existing tabs — no template rebuild required.
-
-## The problem it solves
-
-Sometimes you just need one more tab next to WooCommerce's Description, Additional Information, and Reviews — a sizing guide, a shipping note, a care instructions panel — without rebuilding the entire tabs section.
-
-## How it helps
-
-Woo Add Product Tab appends a single, fully-editable tab to WooCommerce's native tabs, with a title, rich-text content, and control over where it sits in the tab order — all visually, in a few clicks.
-
-## The result
-
-One extra tab exactly where you want it, without touching the rest of your product tabs setup.
-
-*Need to rebuild and restyle the whole tabs area, with multiple custom tabs and accordion support on mobile? See [Woo Custom Product Tabs](woo-custom-product-tabs.md).*

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/woo-cart.md

@@ -1,15 +0,0 @@
-# Woo Cart
-
-A complete, from-scratch cart widget — with instant AJAX quantity updates and deep styling control, no Elementor Pro required.
-
-## The problem it solves
-
-A store's cart page is one of the last steps before checkout, and default cart styling rarely matches the rest of a carefully designed store. Elementor Pro has its own cart widget, but if you're not on Elementor Pro, or you want more granular styling control than it offers, there's a gap.
-
-## How it helps
-
-Woo Cart is a ground-up cart widget: item rows with thumbnail, name, variation details, a quantity stepper, and pricing; a coupon box; and a totals panel with checkout button — all restyled through more than a dozen dedicated style sections. Switch on AJAX quantity updates and shoppers can adjust amounts without a page reload at all, with the totals panel updating live, including coupon and discount rows.
-
-## The result
-
-A cart experience that feels instant and looks exactly like the rest of your store, without needing Elementor Pro.

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/woo-custom-product-tabs.md

@@ -1,15 +0,0 @@
-# Woo Custom Product Tabs
-
-A complete rebuild of your product tabs — styleable down to the reviews and rating form, with a built-in mobile accordion.
-
-## The problem it solves
-
-WooCommerce's default product tabs (Description, Additional Information, Reviews) are functional but offer minimal styling control, and turn into an awkward stacked layout on mobile with no accordion behaviour built in.
-
-## How it helps
-
-Woo Custom Product Tabs replaces the entire tabs area with a fully restyled desktop-tabs / mobile-accordion component. Hide any of the default tabs you don't need, add as many custom tabs as you like — rich text, or an entire embedded Elementor template — and reach deep into the reviews section itself: avatar styling, star ratings, review cards, and the review submission form all get their own dedicated controls.
-
-## The result
-
-A product tabs section that looks genuinely custom-built, with reviews that finally match the rest of your store's design — and a proper accordion on mobile, not just a cramped stack.

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/woo-product-filter.md

@@ -1,17 +0,0 @@
-# Woo Product Filter
-
-Genuine faceted product filtering — category, attribute, brand, or tag — with instant AJAX results and clean, shareable URLs.
-
-## The problem it solves
-
-Shoppers expect to filter by colour, size, brand, or category and see results update instantly, with a URL they can bookmark or share. Building that properly — with correct product counts, dependent filters, and URLs that still work when shared or reloaded — is normally a serious development project.
-
-## How it helps
-
-Woo Product Filter gives you as many filter groups as you need, each pulling from a category, tag, brand, or any custom attribute, displayed as a list or as clickable buttons — including real colour swatches for attributes like colour. Results refresh instantly via AJAX (or update the page URL directly, your choice), term counts update live so shoppers always see what's actually available, and every filtered view has a clean, bookmarkable URL that reproduces the exact same results when shared or reloaded — even with JavaScript disabled.
-
-You can even set up dependent filters — a "Size" group that only appears once a category is chosen, for example — for a genuinely guided filtering experience.
-
-## The result
-
-The kind of faceted filtering shoppers expect from major ecommerce sites, built entirely through Elementor controls.

marketing/dotjuice-elementor-tools-pro/documentation/marketing/widgets/woo-quick-view.md

@@ -1,15 +0,0 @@
-# Woo Quick View
-
-Let shoppers preview a product without ever leaving your shop grid.
-
-## The problem it solves
-
-Every click away from a product grid is a chance for a shopper to lose momentum — and browsing a busy category means a lot of back-and-forth between the grid and individual product pages just to check details, sizes, or images.
-
-## How it helps
-
-Woo Quick View adds a button to every product in your grid that opens the full product view in a popup — sizes, images, description, add to cart — without navigating away. The button appears automatically across your product loops once switched on, including on variable products where it can replace the "Select options" link entirely. Hovering a button quietly preloads the popup content in the background, so by the time a shopper actually clicks, it feels instant.
-
-## The result
-
-A faster, more fluid browsing experience that keeps shoppers on your grid, discovering more products instead of clicking in and out of individual pages.

marketing/dotjuice-elementor-tools-pro/overview.md

@@ -1,4 +1,4 @@
-The premium widget set for serious WooCommerce stores — AJAX product filtering, a fully custom cart, quick view, custom product tabs, frontend ACF forms, and watermark-free screenshots.
+The premium widget set for serious WooCommerce stores — AJAX product filtering, a fully custom cart, quick view, custom product tabs, frontend ACF forms, an on-brand PDF viewer, and watermark-free screenshots.
 
 ### Built for stores that have outgrown the basics
 
@@ -12,9 +12,9 @@ The free Dotjuice Elementor Tools plugin covers the everyday styling gaps in Woo
 
 **Woo Quick View** — lets shoppers preview a product in a popup without leaving your shop grid, triggered by a button that appears automatically across your product loops, complete with hover-preloading so the popup feels instant.
 
-**Woo Custom Product Tabs** — a full rebuild of the WooCommerce product tabs area as a styleable desktop-tabs/mobile-accordion component, with the ability to add unlimited custom tabs and deep styling control down into your reviews and rating form.
+**Woo Custom Product Tabs** — a full rebuild of the WooCommerce product tabs area as a styleable desktop-tabs/mobile-accordion component: add unlimited custom tabs, show or hide any custom tab per product by category, tag, brand or attribute, and style deep into your reviews and rating form.
 
-**Woo Add Product Tab** — the lightweight option when you just need to bolt one extra tab onto the existing WooCommerce tabs, no rebuild required.
+**PDF Viewer** — display brochures, manuals, price lists and menus directly on your pages in a fully styleable viewer with page navigation, zoom, fullscreen, download and print, instead of a download link or the browser's own unstyleable PDF plugin.
 
 **ACF Frontend Form** — let visitors edit Advanced Custom Fields content directly from the front end, using ACF's own native form interface, no admin access required.
 

marketing/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md

@@ -0,0 +1,15 @@
+Let visitors edit Advanced Custom Fields content from the front end — no admin access, no wp-admin, just a form on your page.
+
+#### The problem it solves
+
+Advanced Custom Fields is one of the most powerful tools in WordPress for structured content, but editing it has always meant going into wp-admin. For membership sites, directories, community-submitted content, or client self-service portals, that's a real barrier. Either your users need WordPress accounts with admin access, or you're manually updating their content for them.
+
+#### How it helps
+
+The widget renders ACF's native frontend form directly on your page — including repeaters, flexible content, tabs, and every other ACF field type. It can either update the current post (perfect for single-post templates where users edit their own content) or create a new post of a chosen type (ideal for front-end submissions). All the layout and field behaviour matches the WordPress dashboard, so there's no learning curve for editors.
+
+#### The result
+
+A fully functional front-end editing experience that lets contributors manage their content without ever seeing the WordPress admin. Membership sites, directories, and client portals become self-service, and you stop being the middleman for every content update.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>

marketing/dotjuice-elementor-tools-pro/widgets/pdf-viewer.md

@@ -0,0 +1,15 @@
+Show PDFs properly on your pages — brochures, manuals, price lists and menus, in a viewer that matches your site instead of the browser's.
+
+#### The problem it solves
+
+Putting a PDF on a WordPress page usually means one of two things: a plain download link that sends visitors away from your site into a file manager, or an iframe that hands the document to whatever PDF viewer their browser happens to have. That viewer looks different in Chrome, Safari, Firefox and Edge, carries its own grey toolbar that clashes with every design, can't be styled at all, and on several mobile browsers refuses to display inline — leaving some visitors with a blank box or a forced download.
+
+#### How it helps
+
+The PDF Viewer widget renders the document itself, page by page, as part of your page. The toolbar, buttons, page indicator, background and the page's own border and shadow are all controlled from the Elementor panel, so the viewer looks like it belongs to your site rather than the browser. Visitors get page navigation, zoom, fullscreen, download and print — and you decide which of those they get, hiding any button you'd rather not offer. Only the page being viewed is loaded, so a long brochure opens quickly, and lazy loading keeps a viewer further down the page from slowing the first paint. Files come from your media library or any external URL, and everything renders identically for every visitor.
+
+#### The result
+
+Documents that are genuinely part of your site — read in place, on brand, on every browser and device, with no download step and no jarring hand-off to a viewer you don't control.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/pdf-viewer" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>

marketing/dotjuice-elementor-tools-pro/widgets/woo-cart.md

@@ -0,0 +1,15 @@
+A complete, from-scratch cart widget — with instant AJAX quantity updates and deep styling control, no Elementor Pro required.
+
+#### The problem it solves
+
+WooCommerce's default cart page works, but it's hard to style and even harder to embed into a custom page layout. Elementor Pro's Cart widget exists, but it's locked behind a subscription. If you want a cart that matches the rest of your design without paying for a whole builder upgrade, you're stuck hacking templates or using shortcodes.
+
+#### How it helps
+
+The widget is a fully custom cart implementation built directly on WooCommerce data. It renders its own item rows with thumbnails, product names, variation details, quantity steppers, and line totals — all updating via AJAX without a page refresh. The coupon field is built in, the totals panel shows accurate real-time calculations, and every element is individually styleable from the Elementor panel. Express checkout buttons (Google Pay, Apple Pay, etc.) are fully supported through WooCommerce's standard hooks.
+
+#### The result
+
+A cart page that looks exactly the way you want, works the way your customers expect, and costs nothing extra. No Elementor Pro subscription required, no template overrides, no compromise.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/woo-cart" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>

marketing/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md

@@ -0,0 +1,15 @@
+A complete rebuild of your product tabs — styleable down to the reviews and rating form, with a built-in mobile accordion.
+
+#### The problem it solves
+
+WooCommerce's default product tabs (Description, Additional Information, Reviews) are rigid and difficult to style consistently. On mobile, they become a narrow row of links that's hard to tap, and the content panels have no responsive adaptation. Adding custom tabs with Elementor template content requires overriding the theme or writing custom code.
+
+#### How it helps
+
+The widget replaces the entire product tab system with a fully styleable component. The tab navigation sits above a styled panel box, and every element — tab labels, active states, panel backgrounds, borders, shadows — is controllable from the Elementor panel. You can hide any default WooCommerce tab and add unlimited custom tabs with WYSIWYG content or entire Elementor templates. On mobile, the tab row collapses into an accessible accordion that's easy to navigate by touch.
+
+#### The result
+
+Product tabs that actually match your design. Custom content is easy to add, mobile works naturally, and the whole component feels like a first-class part of your site rather than a WooCommerce default you're stuck with.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>

marketing/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md

@@ -0,0 +1,15 @@
+Genuine faceted product filtering — category, attribute, brand, or tag — with instant AJAX results and clean, shareable URLs.
+
+#### The problem it solves
+
+WooCommerce's built-in product filtering is limited. You can filter by category or attribute, but combining multiple filters, preserving URL parameters, and updating the product grid without a full page reload all require custom development. Shoppers expect to narrow down products by colour, size, brand, and price — all at once — without the page flashing.
+
+#### How it helps
+
+The widget builds a complete faceted filter interface that works with any combination of taxonomies. Choose which taxonomies to include (category, tags, attributes, brands), how they display (checkboxes, dropdowns, buttons), and how they interact. When a shopper selects a filter, the product grid updates instantly via AJAX — no page reload, no scroll reset. The URL updates with clean query parameters, so filtered results are bookmarkable and shareable.
+
+#### The result
+
+A professional, fast product filtering experience that helps shoppers find exactly what they're looking for in seconds. Your conversion rate goes up because the path from "browsing" to "buying" gets shorter and smoother.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>

marketing/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md

@@ -0,0 +1,15 @@
+The content panel that powers your Quick View popup — renders the full product detail inside an Elementor Popup.
+
+#### The problem it solves
+
+A Quick View button is only half the solution. You need a popup that shows the product details — image, price, variations, add-to-cart — in a clean, responsive overlay. Building that popup manually means duplicating product page templates, handling AJAX requests, and styling everything to match.
+
+#### How it helps
+
+This widget is designed to sit inside an Elementor Popup. Drop it into the popup canvas, and it handles everything — fetching the product data, rendering the image gallery, variations, price, and add-to-cart button, and displaying it all in a layout that matches your site. No template duplication, no custom AJAX, no styling conflicts.
+
+#### The result
+
+A complete Quick View experience in minutes. Pair it with the Woo Quick View button widget, drop this into an Elementor Popup, and your shop has a professional Quick View flow without custom development.
+
+<a target="_blank" rel="noopener noreferrer" href="https://docs.dotjuice.co.uk/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup" class="dj-docs-button" style="display: inline-block; padding: 14px 28px; background-color: var(--e-global-color-text); color: var(--e-global-color-primary); text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; margin-top: 8px;">View full documentation</a>