chore: modernize to Docusaurus 3 (from 2.0.0-beta.20)

[billfreeman44]

Upgrades the docs site from Docusaurus 2.0.0-beta.20 → 3.10.1. Fully verified locally on Node 24.18 (docusaurus build succeeds).

What changed

• @docusaurus/core + @docusaurus/preset-classic ^2.0.0-beta.20 → ^3 (resolves 3.10.1). This brings MDX 1 → 3; the docs are plain markdown (no JSX/components), so content builds unchanged.
• posthog-docusaurus 1 → 2 — v2 moved config from themeConfig.posthog to plugin options (plugins: [['posthog-docusaurus', { apiKey, appUrl, enableInDevelopment }]]). Migrated.
• onBrokenMarkdownLinks moved from top-level to markdown.hooks.onBrokenMarkdownLinks (clears the Docusaurus v4 deprecation warning).
• posthog apiKey fallback ' ' → 'phc_placeholder' — posthog-docusaurus v2 rejects an empty/space key, which would fail keyless local/PR builds. CI still injects the real POSTHOG_API_KEY secret.
• prettier 2 → 3, npm-run-all → npm-run-all2, repository object form, pinned publish npm@latest → npm@^11.

Security — 0 vulnerabilities (was 21)

The 21 advisories were entirely in Docusaurus 3.10.1's build/dev toolchain (nothing ships — the deployed site is static files and the npm package is an empty index.js), and all cascaded from just two leaves: serialize-javascript (high, RCE/DoS) and uuid@8. Added minimal overrides:

"serialize-javascript": "^7.0.5",
"uuid": "^11.1.1"

Both are API-stable in the webpack toolchain; the site still builds clean after the override, and npm audit is now 0.

Verified locally (Node 24.18)

• Fresh npm install, npm run build → "Generated static files in build" (index.html + 404.html), no errors, no deprecation warnings.
• npm run lint (prettier) clean. Docs markdown content is byte-unchanged.

Note: the actual gh-pages deploy + npm publish happen in CI; this PR verifies the build. Not merging without your sign-off.

[Copilot]

Pull request overview

Upgrades the documentation site toolchain from Docusaurus 2.0.0-beta.20 to the Docusaurus 3.x line (resolving to 3.10.1 via the lockfile), including associated analytics and tooling adjustments to keep builds/linting and publishing working under the new ecosystem.

Changes:

• Bump Docusaurus, PostHog integration, and Prettier to modern major versions; add targeted overrides for known vulnerable transitive deps.
• Migrate PostHog configuration from themeConfig.posthog to posthog-docusaurus plugin options and move onBrokenMarkdownLinks into the new markdown hook location.
• Pin the publish workflow’s npm upgrade step to npm@^11 (instead of latest) for more stable CI behavior.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
package.json	Updates deps/scripts for Docusaurus 3 + Prettier 3, adds security overrides, and modernizes metadata.
docusaurus.config.js	Migrates PostHog config to plugin options and updates markdown link handling configuration.
.github/workflows/publish.yml	Pins npm upgrade step to npm v11 range for CI publishing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[billfreeman44]

Good catch on the version math, but I'm keeping engines.node at ">=22.0.0". Two reasons:

1. Tightening wouldn't help. npm validates each installed package's engines independently against the running Node — a package's check isn't suppressed by the root project's engines.node. So on a hypothetical Node 22.0–22.22.1 install, npm-run-all2@9's own ^22.22.2 check fails regardless of what this repo declares. Raising this repo's engines.node would only add a second EBADENGINE (the root's own) on that same old Node — strictly worse.
2. It's the consumer contract, and npm-run-all2 is dev-only. npm-run-all2 is a devDependency and is excluded from the published tarball by the files whitelist, so consumers never install it. Coupling the public Node contract to a private dev-tool's patch-level requirement is the wrong tradeoff.

In practice there's no warning at all: CI's setup-node 22/24 resolve to the latest patch of each line (≥22.22.2 and ≥24.15.0) and local dev is on Node 24.18 — all satisfy npm-run-all2@9.