diff --git a/docs/dotjuice-elementor-tools-pro/getting-started.md b/docs/dotjuice-elementor-tools-pro/getting-started.md
index d3ca19b..44fd92b 100755
--- a/docs/dotjuice-elementor-tools-pro/getting-started.md
+++ b/docs/dotjuice-elementor-tools-pro/getting-started.md
@@ -4,7 +4,7 @@
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).
- **Advanced Custom Fields (ACF)**, only for the ACF Frontend Form widget.
diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md
index ab1146a..69b4e77 100755
--- a/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md
+++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md
@@ -47,6 +47,18 @@ 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).
diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md
index cb8eea5..a669eca 100755
--- a/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md
+++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md
@@ -6,6 +6,8 @@ Found in the Elementor panel under **Dotjuice → Woo Product Filter**. Requires
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.
+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 +18,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 +73,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.
diff --git a/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-colours.png b/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-colours.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-colours.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-controls.png b/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/dark-mode-toggle-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/getting-started-admin-menu.png b/docs/dotjuice-elementor-tools/assets/img/getting-started-admin-menu.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/getting-started-admin-menu.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/getting-started-widget-panel.png b/docs/dotjuice-elementor-tools/assets/img/getting-started-widget-panel.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/getting-started-widget-panel.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/keyword-linker-controls.png b/docs/dotjuice-elementor-tools/assets/img/keyword-linker-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/keyword-linker-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/markdown-widget-controls.png b/docs/dotjuice-elementor-tools/assets/img/markdown-widget-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/markdown-widget-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/markdown-widget-product-tab.png b/docs/dotjuice-elementor-tools/assets/img/markdown-widget-product-tab.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/markdown-widget-product-tab.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/product-attribute-colours.png b/docs/dotjuice-elementor-tools/assets/img/product-attribute-colours.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/product-attribute-colours.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/screenshot-api-settings.png b/docs/dotjuice-elementor-tools/assets/img/screenshot-api-settings.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/screenshot-api-settings.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-cache.png b/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-cache.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-cache.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-controls.png b/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/screenshot-capture-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-controls.png b/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-frontend.png b/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-frontend.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-add-to-cart-frontend.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-controls.png b/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-frontend.png b/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-frontend.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-categories-transform-frontend.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-my-account-transform.png b/docs/dotjuice-elementor-tools/assets/img/woo-my-account-transform.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-my-account-transform.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-page-numbers.png b/docs/dotjuice-elementor-tools/assets/img/woo-page-numbers.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-page-numbers.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-controls.png b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-frontend.png b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-frontend.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-frontend.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-rollover.png b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-rollover.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-products-transform-rollover.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-controls.png b/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-controls.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-controls.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-frontend.png b/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-frontend.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woo-taxonomy-list-frontend.png differ
diff --git a/docs/dotjuice-elementor-tools/assets/img/woocommerce-account-settings.png b/docs/dotjuice-elementor-tools/assets/img/woocommerce-account-settings.png
new file mode 100644
index 0000000..0166aaf
Binary files /dev/null and b/docs/dotjuice-elementor-tools/assets/img/woocommerce-account-settings.png differ
diff --git a/docs/dotjuice-elementor-tools/getting-started.md b/docs/dotjuice-elementor-tools/getting-started.md
index 1610d84..d3b50ee 100755
--- a/docs/dotjuice-elementor-tools/getting-started.md
+++ b/docs/dotjuice-elementor-tools/getting-started.md
@@ -1,40 +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.
+
+
+*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.
+- 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))
+
+*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)
-- [Woo Products Transform](widgets/woo-products-transform.md)
-- [Woo Add to Cart Transform](widgets/woo-add-to-cart-transform.md)
-- [Woo Categories Transform](widgets/woo-categories-transform.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.
diff --git a/docs/dotjuice-elementor-tools/product-attribute-colours.md b/docs/dotjuice-elementor-tools/product-attribute-colours.md
index 78de172..3899ab5 100755
--- a/docs/dotjuice-elementor-tools/product-attribute-colours.md
+++ b/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.
+
+
+*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 `#`.
diff --git a/docs/dotjuice-elementor-tools/screenshot-api-settings.md b/docs/dotjuice-elementor-tools/screenshot-api-settings.md
index e84992d..f9c7d19 100755
--- a/docs/dotjuice-elementor-tools/screenshot-api-settings.md
+++ b/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.
+
+
+*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.
diff --git a/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md b/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md
index 0494d48..4abfede 100755
--- a/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md
+++ b/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md
@@ -1,55 +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**.
+
+*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 your global colours 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.
It works with **both** of Elementor's global-colour systems:
- **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/v4 widgets, defined under **Site Settings → Global Variables**.
+- **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**.
-Because modern pages often mix older widgets (which read the legacy colours) with newer atomic widgets (which read 4.x variables), the widget can override both at once from a single toggle.
+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.
-**Important:** this widget only changes colours for elements styled using a global colour or global variable. Anything using a hardcoded colour won't respond to dark mode — the more consistently your design uses global colours/variables, the more complete the effect.
+:::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
+## 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
-At the top, **Global Colour System** decides which colour systems dark mode overrides:
+**Global Colour System** decides which colour systems the toggle overrides:
| Choice | What it does |
|---|---|
-| **Both** *(default)* | Applies the legacy four colours **and** your chosen 4.x variable overrides together — best for pages that mix old and new widgets. |
-| **Legacy only** | Overrides just the four classic Global Colors. |
-| **Variables only** | Overrides just the 4.x global variables, leaving the legacy four untouched. |
+| **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 use a sensible built-in dark default.
+**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** — add a row for each variable you want to change in dark mode: pick the variable from the list of your site's global variables, then set its dark-mode colour. The dark value can be a plain colour, or a reference to one of your palette colours. Add as many rows as you need.
+**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.
-> New variables you create *after* opening the editor won't appear in the list until you reload the editor, because Elementor builds the widget's options once when the editor loads.
+
+*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, choose your **Global Colour System** (leave on **Both** if your site mixes widget types).
-3. Set your Legacy dark colours and/or add variable rows for a palette that works well as a dark theme.
-4. Save and test: click the toggle on the live site and confirm the elements using your global colours/variables 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 colours used site-wide.** If you place more than one Dark Mode Toggle with different settings, the last one clicked "wins" for the whole site until another is clicked. For a single consistent dark mode, use the same settings on every instance, or place the widget in one shared location like your header.
-- If you change the widget's colour settings after already switching dark mode on, toggle it off and back on once (or clear the browser's site data) so it re-reads the new values — the last-used colours are cached in the browser for speed.
-- 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.
diff --git a/docs/dotjuice-elementor-tools/widgets/keyword-linker.md b/docs/dotjuice-elementor-tools/widgets/keyword-linker.md
index fd83608..b3b8be8 100755
--- a/docs/dotjuice-elementor-tools/widgets/keyword-linker.md
+++ b/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**.
+
+*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 (`
`) 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 `
` 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 `
` 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.
diff --git a/docs/dotjuice-elementor-tools/widgets/markdown-widget.md b/docs/dotjuice-elementor-tools/widgets/markdown-widget.md
index 6c779a7..c54d74c 100755
--- a/docs/dotjuice-elementor-tools/widgets/markdown-widget.md
+++ b/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**.
+
+*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 `
`/`` 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 `
`/`` 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.
+
+
+*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.
diff --git a/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md b/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md
index a9e05a2..0e877fb 100755
--- a/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md
+++ b/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**.
+
+*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.
+
+
+*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.
diff --git a/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md b/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md
index 1211c3d..e620f10 100755
--- a/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md
+++ b/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.
+
+*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 `