Initial commit: Docusaurus docker stack and docs

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.