Initial commit: Docusaurus docker stack and docs

docs/dotjuice-pagespeed/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Pagespeed",
+  "position": 4,
+  "link": { "type": "doc", "id": "dotjuice-pagespeed/getting-started" }
+}

docs/dotjuice-pagespeed/advanced.md

@@ -0,0 +1,30 @@
+# Advanced
+
+**Dotjuice → Page speed → Advanced**
+
+## What this tab controls
+
+WordPress's Heartbeat API, XML-RPC, and WooCommerce script loading on non-shop pages.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **WordPress Heartbeat API** | Optimise | Choose **Default** (WordPress's normal behaviour, checking in roughly every 15 seconds), **Optimise** (extends the interval — see below), or **Disable** (removes it entirely). Heartbeat powers autosave, post-locking ("someone else is editing this post") notices, and some plugins' live dashboard updates. |
+| **Heartbeat Interval (seconds)** | 60 | Only used when Heartbeat is set to Optimise. How often it checks in — minimum 15 seconds, whatever you enter is used as the new interval. A longer interval means less background load but a longer delay before autosave/post-lock notices update. |
+| **Disable XML-RPC** | Off | Stops your site responding to XML-RPC requests — the older remote-publishing protocol some legacy apps and (historically) some brute-force attack tools target. Only worth enabling if you don't use an app, service, or plugin that specifically requires XML-RPC (check before enabling; some SEO and cross-posting tools still rely on it). |
+| **Disable WooCommerce Scripts on Non-Shop Pages** | Off | Stops WooCommerce's cart and general styling/scripts from loading on pages outside your shop and cart/checkout flow — see the warning below before enabling. |
+
+## ⚠ Before enabling "Disable WooCommerce Scripts on Non-Shop Pages"
+
+This is a genuinely useful setting for pages that have nothing to do with your shop, but check your **My Account** pages (order history, downloads, addresses) after enabling it — those pages rely on WooCommerce's own styling too, and if they look visibly broken after you turn this on, it's this setting. Test it and confirm your account pages still look right before leaving it enabled on a live site.
+
+## Heartbeat: Optimise vs Disable
+
+**Optimise** (the default) is the safer of the two active choices — it keeps all of WordPress's Heartbeat-dependent features working (autosave, post locking, live plugin dashboards) but checks in less frequently, cutting down on background requests without losing functionality.
+
+**Disable** removes Heartbeat entirely. This means autosave-in-the-background and "someone else is currently editing this" warnings stop working, and any plugin whose live-updating dashboard widgets depend on Heartbeat will stop updating live. Only choose this if you're confident nothing on your site relies on it.
+
+## About XML-RPC
+
+Disabling XML-RPC here uses WordPress's own built-in mechanism to refuse XML-RPC requests — it doesn't hide or remove the `xmlrpc.php` file itself, it simply makes it respond that XML-RPC is turned off. If you need airtight blocking at the server level (rather than the WordPress application level), that typically needs a rule added at your web server or firewall instead.

docs/dotjuice-pagespeed/caching.md

@@ -0,0 +1,45 @@
+# Caching
+
+**Dotjuice → Page speed → Caching**
+
+## 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.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Enable Page Caching** | On | Turns full-page caching on or off entirely. With this off, every other setting on this tab has no effect. |
+| **Separate Cache for Mobile Devices** | On | Stores a distinct cached copy for mobile visitors, detected by user agent. Keeps this on if your theme shows different content or layout on mobile — otherwise mobile visitors could occasionally be served a desktop-cached page or vice versa. |
+| **Cache Pages for Logged-in Users** | Off | See the warning below — this doesn't do what the label suggests. |
+| **Cache Lifetime (seconds)** | 86400 (24 hours) | How long a cached page is considered fresh before it's automatically rebuilt. Minimum 300 seconds (5 minutes), maximum 30 days. |
+
+## How caching stays up to date
+
+You never need to manually clear the cache after normal editing. It happens automatically when you:
+
+- Publish or update any post or page (only that page and your homepage are cleared — the rest of your cached site is untouched)
+- Switch themes
+- Update a plugin or WordPress core
+
+The **Cache Lifetime** setting is a safety net on top of this — a maximum age for any cached page, in case something changes the page without triggering a normal WordPress save (a scheduled event, an external data feed, etc.).
+
+## ⚠ About "Cache Pages for Logged-in Users"
+
+This setting is easy to misread. WordPress admin/editor sessions are excluded from the fastest cache delivery paths regardless of this setting — that part is fixed and can't be turned off, which is exactly what you want (you should always see a live, uncached view of your own site while logged in).
+
+What this toggle actually does is let a logged-in visit *contribute* to building the cache that anonymous visitors later see, on the rare occasions a logged-in request reaches a page that isn't already cached. **We recommend leaving this off** unless you have a specific reason to change it: if you're logged in as an editor or admin and your theme shows you anything personalised (an admin bar styling quirk, a "welcome back" message, draft content preview, etc.), enabling this risks that content being saved into the cache and shown to anonymous visitors afterward.
+
+## Manually clearing the cache
+
+Two ways to force every cached page to rebuild immediately:
+
+- **Clear Cache** button in the Page speed settings toolbar
+- **Clear Cache** button in your WordPress admin bar (visible on every page, front-end and admin) — this one also shows your current cache size and clears the combined CSS/JS files from the [CSS](css-optimisation.md) and [JavaScript](javascript-optimisation.md) tabs at the same time
+
+Use this after making a change that automatic clearing wouldn't catch — a manual template edit, a change made outside the normal post/page editor, or simply to confirm you're looking at a fresh copy of a page while troubleshooting.
+
+## For the fastest possible caching
+
+See [Getting Started](getting-started.md) for the one-time `WP_CACHE` setup step — it enables the fastest of three delivery methods this plugin uses. Caching still works without it, just not at its absolute fastest.

docs/dotjuice-pagespeed/cdn.md

@@ -0,0 +1,34 @@
+# CDN
+
+**Dotjuice → Page speed → CDN**
+
+## What this tab controls
+
+Rewriting your site's stylesheet and script URLs to point at a CDN hostname instead of your own server.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Enable CDN URL Rewriting** | Off | Turns URL rewriting on or off. |
+| **CDN URL** | Empty | The hostname to rewrite asset URLs to (e.g. `https://cdn.yoursite.com`). The plugin doesn't check that this URL is reachable or correctly configured — make sure your CDN is already set up and serving your site's files before enabling this. |
+| **Rewrite These Directories** | `wp-content, wp-includes` | Only URLs containing one of these path segments are rewritten — leaves this as-is unless you have a specific reason to narrow or widen it. |
+
+## What this does and doesn't cover
+
+This setting rewrites the URLs WordPress generates for enqueued stylesheets and scripts — the same files covered by the [CSS](css-optimisation.md) and [JavaScript](javascript-optimisation.md) tabs. It does **not** rewrite:
+
+- Image URLs (`<img>` tags, background images set via CSS)
+- Media Library files linked or embedded in post content
+- Fonts referenced from inside a CSS file's own `@font-face` rules
+
+If your goal is CDN delivery for your whole media library rather than just CSS/JS, you'll need a dedicated media-offload plugin, or your CDN provider's own integration, in addition to this setting.
+
+## Setting it up
+
+1. Confirm your CDN is already configured and correctly mirroring/proxying your site (this plugin doesn't set up the CDN itself — it only rewrites URLs to point at one that's already working).
+2. Enter your CDN's hostname in **CDN URL**, including the `https://` prefix.
+3. Enable **Enable CDN URL Rewriting** and save.
+4. Clear your cache and check a page's source (or your browser's Network tab) to confirm stylesheet and script URLs now point at your CDN hostname and load correctly.
+
+If assets fail to load after enabling this, double-check the CDN URL is exactly correct and that your CDN is actually serving the `wp-content`/`wp-includes` paths — a misconfigured CDN will show as broken styling or a console full of failed requests.

docs/dotjuice-pagespeed/css-optimisation.md

@@ -0,0 +1,34 @@
+# CSS
+
+**Dotjuice → Page speed → CSS**
+
+## 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.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Minify CSS** | On | Strips comments and unnecessary whitespace from stylesheets. Safe on its own — the visual output is identical, just a smaller file. |
+| **Combine CSS Files** | On | Merges your local stylesheets into a single cached file, in the correct dependency order, cutting down the number of separate requests the browser has to make. External stylesheets (Google Fonts, CDN-hosted resources) are always left as their own requests. |
+| **Load Combined CSS Asynchronously** | Off | Removes the combined stylesheet from the render-blocking path — see the warning below before enabling. |
+| **Critical CSS** | Empty | A block of CSS you provide, inlined directly into every page. Required if you enable asynchronous loading (see below). |
+| **Remove Unused CSS (Experimental)** | Off | Not yet active in this version — enabling it currently has no effect. We'll update this guide when it ships. |
+| **Exclude Handles or Filenames** | Empty | A comma-separated list of partial matches (stylesheet handle names or filenames) to skip entirely — useful for a plugin that behaves oddly when combined with others. |
+
+## ⚠ Before enabling "Load Combined CSS Asynchronously"
+
+This is the highest-impact CSS setting and also the one most likely to cause a visible problem if used without preparation. Removing the stylesheet from the render path means the browser paints the page *before* your CSS has loaded — if you haven't told it what the essential above-the-fold styling looks like, visitors will briefly see unstyled HTML (a "flash of unstyled content," or FOUC) before your CSS kicks in.
+
+**Always set Critical CSS first.** This should be the minimum styling needed to render what's visible without scrolling: your body font and background colour, header, navigation, and hero section. A tool like a critical CSS generator (search for "critical CSS generator" — several free online tools exist) can produce this automatically by analysing your homepage.
+
+**Test on a staging copy of your site first**, particularly if your site has several very different-looking page templates (a landing page vs. a blog post vs. a WooCommerce product page) — one block of critical CSS may not cover all of them equally well.
+
+## Excluding a stylesheet
+
+If a specific plugin's styling looks wrong after combining, add its stylesheet handle or filename to **Exclude Handles or Filenames**. You can find a stylesheet's handle using your browser's developer tools (Network tab, filter by CSS) — the filename usually gives it away, or check the plugin's own documentation.
+
+## What's not affected
+
+External stylesheets — Google Fonts served from `fonts.googleapis.com`, CDN-hosted libraries, anything not physically hosted on your own server — are never combined or minified. They're already optimised by whoever serves them, and combining them isn't possible across domains.

docs/dotjuice-pagespeed/database.md

@@ -0,0 +1,34 @@
+# Database
+
+**Dotjuice → Page speed → Database**
+
+## 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.
+
+## Manual cleanup
+
+Each card shows a live count for its category. Click **Clean** on any card to run that cleanup immediately — the count updates in place once it's done, no page reload needed.
+
+| Card | What it removes |
+|---|---|
+| **Post Revisions** | Every saved revision of every post and page. WordPress creates a new revision each time you save a draft, and by default never removes old ones — a frequently-edited page can accumulate dozens. |
+| **Auto Drafts** | Posts WordPress auto-saved as blank drafts that were never actually published or intentionally saved (the "Auto Draft" entries you sometimes see if you open the editor and navigate away). Running this also sweeps up any leftover metadata from posts already deleted elsewhere. |
+| **Spam Comments** | Comments already marked as spam by your spam filter — this doesn't touch legitimate comments, only ones already flagged. |
+| **Transients** | Expired cached data that plugins temporarily store in your database (API responses, computed values, etc.) and were supposed to clean up themselves once expired, but often don't. Only expired entries are removed — anything still active and in use is left alone. |
+| **Orphan Post Meta** | Metadata rows left behind after their parent post was deleted through some other means, with nothing left to clean them up. |
+| **Optimise Tables** | Runs a table optimisation pass across your database, reclaiming space left behind by all the deletions above and rebuilding indexes for faster queries. Worth running after a large cleanup, or periodically as routine maintenance. |
+
+## Scheduled cleanup
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Enable Scheduled Database Cleanup** | Off | Turns on automatic cleanup running in the background on the schedule you choose below. |
+| **Remove Post Revisions / Auto Drafts / Spam Comments / Expired Transients** | All off | Choose which categories the scheduled cleanup handles automatically. Each is independent — enable only the ones you want running unattended. |
+| **Cleanup Frequency** | Weekly | How often the scheduled cleanup runs: Daily, Weekly, or Monthly. |
+
+Note that scheduled cleanup only covers the four categories above — **Orphan Post Meta** and **Optimise Tables** are manual-only actions, run them from the cards above whenever you'd like.
+
+## Recommended approach
+
+For most sites, weekly scheduled cleanup of revisions, drafts, and spam is a safe "set and forget" choice. Transients change more often and are generally safe to include too. Table optimisation is worth running manually every month or two, or right after your first big cleanup on a site that's accumulated years of bloat.

docs/dotjuice-pagespeed/getting-started.md

@@ -0,0 +1,40 @@
+# Getting Started
+
+## 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.
+
+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.
+
+## Sensible defaults
+
+The plugin ships with the safest, most broadly compatible optimisations already switched on: page caching, mobile-aware caching, CSS/JS minification, CSS combining, JS deferring, HTML minification, emoji script removal, lazy loading, font-display swap, cache preloading after publish, and font preloading. These are the settings virtually every WordPress site benefits from with no downside.
+
+Settings that carry more risk of visibly breaking a page if your theme or plugins do something unusual — CSS/JS combining across the board, async CSS loading, JavaScript delay-until-interaction, CDN rewriting — are left off by default so you can enable and test them deliberately.
+
+## The one-time setup step: enabling the fast cache path
+
+For the fastest possible caching (page loads served in milliseconds rather than tens of milliseconds), your site needs one line added to `wp-config.php`:
+
+```php
+define( 'WP_CACHE', true );
+```
+
+The plugin tries to add this automatically when you activate it. If it can't — for example because `wp-config.php` isn't writable by PHP on your hosting — you'll see a persistent notice in your admin dashboard with a **Retry automatically** button, or you can add the line yourself just above the `/* That's all, stop editing! */` comment.
+
+**Your site works fine without this.** If the automatic fast path isn't available, caching still runs through a normal WordPress request — just a little slower than the bypass path. Nothing breaks; you simply don't get the absolute fastest response times until it's in place.
+
+## Recommended first steps
+
+1. **Leave the defaults as they are** for your first save — they're the safest baseline.
+2. **Set your LCP image** on the Preload tab (see [Preload](preload.md)) — this is the single highest-impact five-minute change you can make for your PageSpeed score.
+3. **Clear your cache and reload your site** in an incognito/private window to confirm everything looks right.
+4. **Work through the optional tabs one at a time** — CSS async loading and JS delay give the biggest additional speed gains but are worth testing on staging first if your site is complex (see the warnings in [CSS Optimisation](css-optimisation.md) and [JavaScript Optimisation](javascript-optimisation.md)).
+
+## If something looks broken after enabling a setting
+
+Every optimisation on this plugin can be switched off individually. If a page looks wrong after a change:
+
+1. Click **Clear Cache** (top toolbar or the button in your WordPress admin bar) and reload — a stale cached page is the most common cause of "it looks broken."
+2. If it's still wrong, turn off the most recently changed setting and clear the cache again.
+3. See [Troubleshooting](troubleshooting.md) for the settings most likely to cause visible issues and what they need to work safely.

docs/dotjuice-pagespeed/html-optimisation.md

@@ -0,0 +1,26 @@
+# HTML
+
+**Dotjuice → Page speed → HTML**
+
+## What this tab controls
+
+HTML minification, removal of unnecessary version query strings and default WordPress scripts, Google Fonts display behaviour, and DNS prefetch hints.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Minify HTML Output** | On | Strips HTML comments and collapses extra whitespace in your page's final output. Code inside `<script>`, `<style>`, `<pre>`, and `<textarea>` tags is left untouched, and browser-specific IE conditional comments are preserved. |
+| **Remove Version Query Strings from Assets** | On | Strips the `?ver=6.7`-style query string WordPress appends to your own local stylesheets and scripts. This doesn't reduce file size or request count on its own — its purpose is compatibility with hosting, proxy, or CDN configurations that don't cache URLs containing a query string. External assets are left untouched. |
+| **Disable WordPress Emoji Scripts** | On | Removes the script WordPress loads on every page to support emoji rendering on older browsers that don't have native emoji support. All modern browsers render emoji natively, so this is safe to leave on for virtually every site. |
+| **Disable oEmbed (WordPress embeds)** | Off | Removes the discovery markup and script WordPress uses to let *other* sites embed your content automatically, and to embed content (tweets, YouTube videos, etc.) that you've pasted as a bare URL into your own posts. Embeds you've already added to existing content keep working — this only stops the discovery/JS layer, not embeds already saved into your posts. |
+| **Add font-display: swap to Google Fonts** | On | Adds `display=swap` to your Google Fonts stylesheet URL, so browsers show your text immediately in a system fallback font and swap to the web font once it's downloaded — rather than hiding the text entirely until the font arrives. Only applies to fonts loaded the standard WordPress way; a font hardcoded directly into your theme's template files isn't affected. |
+| **DNS Prefetch Domains** | Empty | One domain per line (e.g. `//fonts.gstatic.com`). Tells the browser to resolve these domains' DNS in advance, shaving a small amount of latency off the first request to each one. Useful for third-party services your site depends on that aren't already covered automatically — see [Preload](preload.md) for the domains handled automatically. |
+
+## When to enable "Disable oEmbed"
+
+If you don't use WordPress's automatic embed feature (pasting a bare YouTube or Twitter/X URL on its own line to have it turn into an embedded player automatically) and you don't need other sites to be able to embed your posts, this is safe to enable and removes a small amount of unnecessary markup and script loading from every page.
+
+## Note on Google Fonts
+
+The `font-display: swap` setting only touches fonts loaded the way WordPress expects — through the standard style-loading system. If your theme or page builder hardcodes a `<link>` tag to Google Fonts directly in a template file, or loads fonts via a CSS `@import`, this setting won't reach it. Most themes and Elementor's own font loading work correctly with this setting.

docs/dotjuice-pagespeed/images.md

@@ -0,0 +1,24 @@
+# Images
+
+**Dotjuice → Page speed → Images**
+
+## What this tab controls
+
+Lazy loading of images and iframes, and automatic width/height attributes to prevent layout shift.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Lazy Load Images** | On | Adds native browser lazy loading to images below the fold, using the standard `loading="lazy"` attribute — no JavaScript library involved. Images already handled by another lazy-load plugin, marked as always-load, or that WordPress itself has already flagged as your highest-priority image (see below) are automatically skipped. |
+| **Lazy Load Iframes and Videos** | On | Same native lazy loading applied to embedded iframes (YouTube embeds, maps, and similar). |
+| **Add Missing Width and Height Attributes** | On | Scans images in your post/page content and adds explicit width and height where they're missing, so the browser can reserve the right amount of space before the image downloads — preventing the page from visibly jumping around as images load in (this is what Google's Cumulative Layout Shift metric measures). Only applies to images inside your actual post/page content; images in theme templates, widgets, or headers/footers aren't covered. |
+| **Serve WebP Images (when available)** | Off | Not yet active in this version — enabling it currently has no effect. We'll update this guide when it ships. |
+
+## How this connects to your LCP image
+
+If you've set an **LCP Image URL** on the [Preload](preload.md) tab, that specific image is automatically excluded from lazy loading and instead forced to load with maximum priority — regardless of the Lazy Load Images setting above. You don't need to do anything extra here; setting the LCP image on the Preload tab is enough.
+
+## Why native lazy loading
+
+Older lazy-load techniques rely on JavaScript to detect scroll position and swap in a placeholder image, which adds its own script weight and can cause a visible blank flash before the real image appears. The `loading="lazy"` attribute used here is built into every modern browser, adds no extra script, and the browser itself decides the ideal moment to start fetching each image — typically well before it scrolls into view, so there's no visible delay.

docs/dotjuice-pagespeed/javascript-optimisation.md

@@ -0,0 +1,40 @@
+# JavaScript
+
+**Dotjuice → Page speed → JavaScript**
+
+## What this tab controls
+
+Minification and combining of local scripts, deferred loading, delayed loading until user interaction, and manual exclusions.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Minify JavaScript** | On | Strips comments and unnecessary whitespace from scripts. If minifying a particular script would risk breaking it, the plugin automatically falls back to serving it unminified rather than risk broken code. |
+| **Combine JavaScript Files** | Off | Merges eligible local scripts into a single file. jQuery, Elementor scripts, WordPress core scripts, payment processor scripts, and anything carrying page-specific data are automatically excluded and kept separate — see below. |
+| **Defer JavaScript Loading** | On | Adds the browser's native `defer` behaviour to local scripts, so they download in the background and run only after the page's HTML has finished parsing, instead of blocking it. |
+| **Delay JavaScript Until User Interaction** | Off | Holds external scripts back entirely until the visitor's first scroll, click, tap, or key press — see the warning below. |
+| **Additional Exclude Handles or Filenames** | Empty | A comma-separated list of partial matches to exclude from combining, deferring, and delaying. |
+
+## Already excluded automatically
+
+You don't need to manually exclude these — the plugin recognises them and leaves them alone:
+
+- jQuery and jQuery Migrate
+- Elementor's own scripts
+- WordPress core scripts (block library, polyfills, translation files)
+- Any script with data attached via `wp_localize_script()` (this is how many plugins pass AJAX URLs and security tokens to their scripts — combining or delaying it would break that plugin)
+- Payment processor scripts (Stripe, PayPal, and similar) — these are never delayed, since checkout flows often depend on them being ready immediately
+- Detected webpack/module bundles, which can break if concatenated with unrelated code
+
+## ⚠ Before enabling "Delay JavaScript Until User Interaction"
+
+This is the most aggressive JavaScript setting and delivers the biggest gain in initial load speed, but it means anything relying on those scripts genuinely won't run until the visitor first interacts with the page — no scroll, click, or key press means no script execution. For most sites this is invisible (analytics, chat widgets, and marketing pixels don't need to fire in the first fraction of a second), but if you have a script that must run immediately for the page to work correctly, exclude it by handle or filename first, or test thoroughly before relying on this in production.
+
+## Excluding a script
+
+Same approach as CSS: find the script's handle or filename using your browser's developer tools, then add it to **Additional Exclude Handles or Filenames**. Do this if a specific plugin's functionality stops working after combining or delaying is enabled.
+
+## A note on combining with page builders
+
+If your site is built with Elementor or a similar builder, don't expect **Combine JavaScript Files** to reduce every script down to one file — builder and block scripts are deliberately excluded from combining to avoid runtime conflicts between JavaScript modules. This is intentional and keeps your site stable; the combining still helps for your theme's and simpler plugins' scripts.

docs/dotjuice-pagespeed/preload.md

@@ -0,0 +1,34 @@
+# Preload
+
+**Dotjuice → Page speed → Preload**
+
+## 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.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **LCP Image URL** | Empty | The direct URL of your Largest Contentful Paint image — see below, this is the single most effective setting on this tab. |
+| **Preload Cache After Publish** | On | The moment you publish or update a post, the plugin visits that page itself in the background a few seconds later, so the cache is rebuilt and ready before a real visitor arrives. Only meaningful if [page caching](caching.md) is switched on. |
+| **Preload Web Fonts** | On | Adds connection preconnect hints for Google Fonts if you use them, and preload hints for your site's own locally-hosted `.woff2` font files, so fonts start downloading as early as possible instead of being discovered only once the browser reaches the CSS that references them. |
+| **Auto Prefetch Common Third-party Domains** | On | Automatically detects whether your site actually loads from Google Fonts, Google Analytics, Google Tag Manager, Facebook, or jsDelivr, and adds a DNS prefetch hint only for the ones genuinely in use — so the browser resolves those domains' DNS in advance without wasting lookups on services you don't use. |
+| **Preconnect Origins** | Empty | One origin per line (e.g. `https://api.example.com`) for any other third-party service your site depends on that isn't covered automatically above. Opens the connection (DNS + TLS handshake) in advance of the first real request to that origin. |
+| **Preload from Sitemap** button | — | Visits every URL listed in your `sitemap.xml` in the background, warming the cache for your entire site in one go. |
+
+## Setting your LCP image — the highest-impact five minutes you'll spend
+
+Your **Largest Contentful Paint** score — one of the three Core Web Vitals Google uses for ranking and reports directly in PageSpeed Insights — is almost always determined by one specific image: your hero banner, or whatever the single largest visible element is when a page first loads.
+
+1. Find the image you consider your "hero" for a page (or use the same one for a template that repeats across many pages).
+2. Right-click it in your browser and copy its image address, or find its URL in the Media Library.
+3. Paste that URL into **LCP Image URL**.
+
+This does two things automatically: it tells the browser to fetch that specific image with maximum priority instead of waiting to discover it, and it also excludes that exact image from [lazy loading](images.md) — so the two settings never work against each other.
+
+## Warming your whole site at once
+
+If you're setting this plugin up on a site that already has a lot of published content, click **Preload from Sitemap** after saving your settings. This visits every URL in your sitemap so the cache is ready for real visitors immediately, rather than each page only being cached the first time someone happens to land on it.
+
+For a smaller site this finishes in moments; for a very large site with thousands of URLs, expect it to take a while, since every page is visited individually to build its cache.

docs/dotjuice-pagespeed/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting
+
+## 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.
+2. If it's still wrong, identify the most recently changed setting and turn it off, then clear the cache again to confirm that was the cause.
+3. Check the notes below for the settings most likely to cause a visible issue.
+
+## Settings most likely to need attention if something looks wrong
+
+| Setting | Tab | What to check |
+|---|---|---|
+| **Load Combined CSS Asynchronously** | CSS | Causing a flash of unstyled content? You need Critical CSS filled in — see [CSS Optimisation](css-optimisation.md). |
+| **Combine JavaScript Files** / **Delay JavaScript Until User Interaction** | JavaScript | A feature stopped working? Find its script's handle or filename in your browser's developer tools and add it to the exclude field. |
+| **Disable WooCommerce Scripts on Non-Shop Pages** | Advanced | My Account page (orders, downloads) look unstyled? This is the setting — check it isn't excluding those pages incorrectly for your theme. |
+| **Cache Pages for Logged-in Users** | Caching | Seeing content meant only for logged-in users appear for anonymous visitors? Turn this off and clear the cache. |
+| **WordPress Heartbeat: Disable** | Advanced | Autosave or "someone else is editing this" notices stopped working? Switch back to Optimise instead of Disable. |
+
+## "Add define('WP_CACHE', true) to your wp-config.php" notice won't go away
+
+The plugin tries to add this automatically when activated. If your hosting doesn't allow it to write to `wp-config.php`, you'll see this notice with a **Retry automatically** button. If retrying doesn't clear it, add the line yourself:
+
+```php
+define( 'WP_CACHE', true );
+```
+
+Place it above the `/* That's all, stop editing! */` line near the bottom of `wp-config.php`. Your site caches correctly either way — this notice is about reaching the *fastest* of three delivery methods, not about caching being broken.
+
+## Cache directory not writable
+
+If you see a notice that `wp-content/cache/` isn't writable, your hosting needs that directory (and the plugin's subfolder within it) set to permission 755. Most hosts allow this by default; shared hosting with unusually strict permissions occasionally needs it set manually via your file manager or hosting support.
+
+## A specific plugin or theme feature stopped working
+
+Most compatibility issues trace back to combined CSS/JS. Add the affected stylesheet or script to the **Exclude Handles or Filenames** field on the relevant tab ([CSS](css-optimisation.md) or [JavaScript](javascript-optimisation.md)) rather than turning combining off entirely — this keeps the optimisation for everything else while carving out the one exception you need.
+
+## Before uninstalling
+
+Clear your cache manually first, and if you've been using the automatic `WP_CACHE` setup, you may want to remove `define( 'WP_CACHE', true );` from `wp-config.php` yourself afterward — uninstalling the plugin doesn't automatically remove that line.