Repository navigation
Description
Summary
Audit of every screenshot reference in docs/ (English source). Findings:
- 147 image files tracked under
static/img/(admin/,config/,installation/). - 98 unique images are actually referenced from English docs.
- 48 image files are orphans (exist on disk, never referenced). Several are exactly the per-step screenshots that the docs should be using but are not — they need rewiring before any new captures are taken.
- 27 doc pages reuse the same image two or more times within a single page (a single image illustrating up to 14 different UI states). This is the primary "same screenshot used several times" pattern that needs replacing.
- 28 addon pages under
docs/addons/*/index.mdxcontain zero screenshots.
The full inventory is tracked across the child issues linked below. This master issue is the place for the shared capture playbook and the cross-cutting checklist.
Worst offenders (one image used many times in one page)
| Page | Image | Times | Child issue |
|---|---|---|---|
user-guide/payment-gateways/tax-handling.md |
settings-taxes.png |
15× | Payment Gateways |
user-guide/integrations/zapier.md |
webhooks-list.png |
14× | Integrations |
user-guide/configuration/creating-discount-codes.md |
discount-codes-list.png |
14× | Configuration |
user-guide/integrations/zapier-register-account.md |
webhooks-list.png |
12× | Integrations |
user-guide/payment-gateways/stripe.md |
settings-payment-gateways.png |
12× | Payment Gateways |
user-guide/payment-gateways/getting-paid.md |
settings-general.png + settings-payment-gateways.png |
11× + 7× | Payment Gateways |
user-guide/client-management/account-page.md |
dashboard.png |
10× | Client Management |
user-guide/domain-mapping/how-to-configure-domain-mapping.md |
domains-list.png + settings-domain-mapping.png |
9× + 7× | Domain Mapping / Admin |
user-guide/miscellaneous/sending-emails-and-broadcasts.md |
broadcasts-list.png + settings-emails.png |
9× + 5× | Domain Mapping / Admin |
user-guide/integrations/webhooks.md |
webhooks-list.png |
8× | Integrations |
user-guide/configuration/checkout-forms.md |
multiple (4 distinct images, 15 refs) | 15× | Configuration |
user-guide/configuration/site-templates.md |
multiple (5 distinct, 16 refs) | 16× | Configuration |
user-guide/configuration/customizing-your-registration-form.md |
multiple (3 distinct, 14 refs) | 14× | Configuration |
user-guide/configuration/creating-your-first-subscription-product.md |
multiple (5 distinct, 13 refs) | 13× | Configuration |
user-guide/client-management/upgrading-a-plan.md |
multiple (2 distinct, 8 refs) | 8× | Client Management |
user-guide/client-management/canceling-a-membership.md |
memberships-list.png |
6× | Client Management |
user-guide/client-management/client-websites.md |
customers-list.png |
6× | Client Management |
user-guide/payment-gateways/manual-payments.md |
multiple (2 distinct, 6 refs) | 6× | Payment Gateways |
user-guide/payment-gateways/paypal.md |
settings-payment-gateways.png |
5× | Payment Gateways |
user-guide/configuration/the-registration-flow.md |
multiple (3 distinct, 9 refs) | 9× | Configuration |
user-guide/client-management/downgrading-a-plan.md |
memberships-list.png |
3× | Client Management |
| Six addon pages | addons-page.png |
2× each | Addons |
Child issues
- Integrations — zapier, zapier-register-account, webhooks
- Payment Gateways — stripe, paypal, manual-payments, getting-paid, tax-handling
- Configuration — checkout-forms, creating-discount-codes, customizing-your-registration-form, creating-your-first-subscription-product, site-templates, the-registration-flow, auto-search-and-replace-in-site-templates
- Client Management — account-page, upgrading-a-plan, canceling-a-membership, downgrading-a-plan, client-websites
- Domain Mapping, Administration & Miscellaneous — how-to-configure-domain-mapping, touring-the-admin-panel, managing-memberships, sending-emails-and-broadcasts
- Addon docs missing screenshots — 28 addon
index.mdxpages with no images - Rewire existing orphan screenshots — quick wins where the correct file already exists in
static/img/but the doc still references a generic one
Links to each child issue will be added in a follow-up comment.
Screenshot capture playbook
This playbook is the single source of truth referenced by every child issue. Follow it for every screenshot you take or replace.
1. Local environment
The docs are written against a local WordPress Multisite that resolves at:
http://wordpress.local:8080
Login: navigate to http://wordpress.local:8080/wp-login.php, username admin, password admin.
If wordpress.local does not resolve, add it to /etc/hosts:
127.0.0.1 wordpress.local
If a local stack is not running yet, the project ships everything you need under the Multisite Ultimate test environment (use the same admin/admin credentials whichever way you spin it up — Docker, Local, Lando, valet, etc.). Open the Network Admin dashboard (/wp-admin/network/) — every Ultimate Multisite menu lives under Network Admin → Ultimate Multisite.
2. Seed data (so screenshots are not empty)
Many of the current screenshots show empty/zero state which looks unfinished in the docs. Before capturing, make sure each list has realistic but innocuous data:
- Customers: 6–10 with varied join dates and at least one cancelled.
- Memberships: at least one Active, one Trialing, one On Hold, one Cancelled, one Expired.
- Sites: 6–10 sites across two or three plans.
- Products: at least three plans (Free, Basic, Pro) and one Package/Service.
- Domains: two mapped custom domains, one in
Ready, one inChecking DNS. - Payments: a mix of
Completed,Pending,Refundedso the list looks real. - Discount codes: at least one percentage code, one fixed-amount, one expired.
- Broadcasts: one Email broadcast, one Notice broadcast, one Draft.
- Webhooks: one configured endpoint plus the default ones.
- Events: leave the events log running so it has recent entries.
Use names that look generic but professional. Never use real customer data. Email addresses should be customer-N@example.com, names from a clearly fictional list (e.g. Jane Doe, Acme Designs, Beach Studio).
3. Browser and viewport
Use a clean Chrome / Chromium / Firefox profile (incognito or a dedicated profile) with:
- No browser extensions visible (Grammarly, Honey, password manager toolbars, dev-tools panels).
- Default zoom 100%.
- Light mode WordPress admin colour scheme (
Users → Your Profile → Color Scheme → Default).
Resize the browser window so the captured screenshot is no wider than necessary. Recommended viewports:
- Settings / list / table pages: 1280×800 (DPR 1) or 1280×900. This is wide enough to show the WP admin sidebar plus the page content without horizontal scroll, and narrow enough that the right-hand whitespace doesn't dominate the screenshot.
- Edit forms / modals / dialog boxes: 1024×768 is plenty; the screenshot should focus on the form, not the surrounding chrome.
- Frontend checkout / pricing tables: 1366×900 desktop, plus a 414×900 mobile capture if the page describes mobile behaviour.
If you need a really focused capture (e.g. a single toggle, a single button), crop tightly after taking the screenshot — don't try to do it with browser-resize alone. Aim for 400–900 pixels wide for "inline" screenshots that illustrate one control.
4. Capture mechanics
Two acceptable workflows:
- DevTools device toolbar (Chrome
Cmd+Shift+M/Ctrl+Shift+M): set "Responsive" to the viewport above, then⋮ → Capture screenshot. This gives you pixel-exact output and excludes the OS chrome. - OS screenshot tool with window selection: macOS
Cmd+Shift+4then pressSpaceand click the window; WindowsWin+Shift+S; GNOMEPrtSc → Screenshot a window. Make sure no notification toasts are visible.
After capture:
- Crop to remove dead space, but keep enough context that the reader can locate the control on the screen (the immediate breadcrumb / heading / surrounding label).
- Annotate sparingly. If you must, use the
annotationstyle already used instatic/img/installation/multisite-wizard/(red rounded rectangles, no shadows, no arrows pointing to obvious things). - Strip metadata (
exiftool -all= file.pngor equivalent) — no need to leak the capture machine. - Optimise with
oxipng -o2 file.pngorpngquant --quality=85-95 --speed 1 file.png. Target file size under 200 KB, ideally under 100 KB.
5. File names and placement
Existing naming convention:
static/img/admin/<short-name>.png— Network Admin pages and dialogs that the super admin sees (memberships-list.png,customer-edit.png,webhooks-list.png).static/img/config/<short-name>.png— Settings pages and product / discount / checkout editors (settings-payments-full.png,discount-code-edit.png).static/img/installation/<short-name>.png— One-time setup wizards.static/img/installation/multisite-wizard/<short-name>.png— Multisite wizard sub-flow.
Keep names hyphenated, lowercase, descriptive of the screen — not the doc that uses it. Reuse the existing names when re-capturing the same screen so docs that link them don't need editing. Where the docs reference a generic placeholder, add new files with a more specific name (e.g. discount-code-edit-percentage.png, stripe-webhook-endpoint-url.png).
Several files already exist on disk but no doc references them yet — see the Rewire existing orphan screenshots issue for the list; in many cases the right fix is "wire up the existing file" before capturing anything new.
6. After replacing screenshots
- Run
npm run buildandnpm run serveto inspect each affected page locally and confirm every image renders. - Re-run any image-optimisation step that CI relies on.
- Translations under
i18n/*/may reference English filenames — the translation pipeline picks up replaced files automatically when filenames stay the same, but new filenames must be added to the relevant translated markdown. Runpython3 fix-i18n-images.py(already in the repo) afterwards if any image paths change. - Commit screenshots and the doc edits together so review is one diff.
7. Acceptance criteria for closing a child issue
- Every alt-text in the affected doc has a screenshot whose content actually matches the alt-text.
- No image appears more than once in the same page unless the page is genuinely re-referencing the same screen (rare; document the reason in the PR description if so).
- Each new file is under 200 KB and metadata-stripped.
npm run buildsucceeds.i18n/*/builds pass (the CI workflow handles this).
Audit captured with git ls-files + a Python reference counter against docs/**/*.{md,mdx} on main.
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.
Activity
superdav42 commentedon May 19, 2026
Child issues
index.mdxpages with zero screenshotsstatic/img/(markdown-only quick wins; good first issue)Suggested order of work:
wordpress.local:8080. Group captures by Network Admin area (Settings → Payments, Settings → Taxes, Domains, Broadcasts, etc.) so one session of capturing covers multiple doc pages.Issue #78 stays open until all child issues are closed.
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.
superdav42 commentedon May 19, 2026
Cross-link: an interactive session published a parallel audit at #64 about a minute before this one (both ran from the same prompt). The two cover the same problem from different angles:
Both bodies have the same capture playbook (1280×800, wordpress.local:8080 admin/admin, < 200 KB PNG). The findings differ only in coverage:
Suggested consolidation: keep #64 as the program tracker, fold #78's extra findings into it as new child issues for the "Future work" bullets (orphan rewire, addon docs, tax/discount/domain/email reuse), and close #79 / #80 as superseded by the narrower #65 / #66 / #67 / #74. Happy to do that on request.
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.
superdav42 commentedon May 19, 2026
Duplicate of #64. The two audits ran in parallel and reached the same overall finding. Net-new content from this audit has been transferred to a gap-analysis comment on #64 (#64 (comment)). Closing.
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.