[Enhancement] Migrate Vuepress to 2x

[jonobr1]

Summary

Migrate the Two.js documentation site (wiki/) from VuePress 1.x (^1.9.x) to VuePress 2.x for long-term maintenance, improved performance (Vite / webpack5 support), modern Node compatibility, and access to the new plugin/theme architecture.

Current setup:

• VuePress 1.9.x (vuepress, @vuepress/plugin-google-analytics, @vuepress/plugin-nprogress, vuepress-plugin-sitemap)
• Custom theme extension at wiki/.vuepress/theme/index.js
• Dynamic sidebar generation in wiki/.vuepress/config.js
• Custom redirects in wiki/.vuepress/enhanceApp.js
• Deployment script: deploy.sh publishing wiki/.vuepress/dist
• Uses legacy Node version per .nvmrc note in README.md

Goals

• Upgrade to VuePress 2.x and compatible plugin equivalents
• Preserve all existing routes, redirects, and SEO-meta
• Maintain current design & navigation (Docs / Examples / Changelog)
• Ensure Google Analytics continues to function (migrate to GA4 if desired)
• Keep build output path & deploy flow stable (or adapt deploy.sh)
• Remove 1.x-only configs (e.g. enhanceApp.js API changes)

Non-Goals

• Redesign of docs layout (minimal visual changes)
• Content rewrite
• Migration of hosting infra (only build tooling)

High-Level Migration Plan

1. Dependency Audit
   • Remove all 1.x VuePress + plugin packages.
   • Add vuepress@^2 and official 2.x plugins (@vuepress/plugin-google-analytics OR adopt GA4 alternative, @vuepress/plugin-search / docsearch if needed, sitemap replacement).
2. Node / Tooling Alignment
   • Update .nvmrc (if needed) to a Node version supported by VuePress 2.
   • Confirm CI / deployment Node version alignment.
3. Config Migration (wiki/.vuepress/config.js)
   • Convert exported object to defineUserConfig pattern.
   • Move themeConfig changes to 2.x format (sidebar, navbar).
   • Confirm lastUpdated now requires @vuepress/plugin-git.
   • Migrate head tags (syntax unchanged).
4. Redirect Handling
   • Replace enhanceApp.js redirect logic with @vuepress/plugin-redirect (or custom client app enhance using clientAppEnhance.{js,ts} in 2.x).
   • Ensure /projects/ → /examples/ and /docs/ → /docs/two/ still work.
5. Theme Extension
   • Replace extend: '@vuepress/theme-default' with 2.x theme usage (defaultTheme({...})).
   • If customization shallow: drop custom theme folder if unnecessary; else refactor into clientAppSetup / layout overrides.
6. Dynamic Sidebar Generation
   • Preserve existing generator using synchronous FS reads; adapt structure to 2.x sidebar array / object format.
7. Plugins
   • Google Analytics: For UA (deprecated) either (a) keep temporarily if still functioning or (b) migrate to GA4 via gtag snippet in head.
   • Sitemap: Use community 2.x sitemap plugin (e.g. vuepress-plugin-sitemap2) or build post-process script.
   • Search: Replace deprecated @vuepress/search boolean with @vuepress/plugin-search or consider Algolia DocSearch.
   • Register Components (if implicitly used by 1.x) — add @vuepress/plugin-register-components if needed.
8. Markdown Options
   • Confirm line numbers config moves to markdown: { code: { lineNumbers: true } } (or current 2.x equivalent).
9. Build & Deploy
   • Update package.json scripts: vuepress dev wiki → vuepress dev wiki (same), confirm output (still wiki/.vuepress/dist).
   • Validate deploy.sh still points to correct dist directory.
10. Testing & Validation

• Local: dev server parity check (navigation, examples, code blocks, image paths).
• Production build: diff HTML head tags, canonical links, and route count.
• Lighthouse / bundle size opportunistic checks.

11. Backwards Compatibility

• Add temporary netlify/vercel redirect rules (if external hosting) for any changed paths.

12. Cleanup

• Remove unused theme or plugin code.
• Update README.md and wiki/README.md to reflect VuePress 2 usage & Node version.

13. Follow-Up (Optional)

• Adopt Algolia search
• GA4 full migration
• Add PWA plugin if desired.

Detailed Task Checklist

• Create docs-migration-vp2 branch
• Remove VuePress 1.x dependencies from package.json
• Add VuePress 2 core + required plugins
• Add / update .nvmrc Node version (>=16 or as required)
• Refactor config.js to defineUserConfig pattern
• Replace theme/index.js extension with 2.x defaultTheme config
• Migrate enhanceApp.js → clientAppEnhance.js (or plugin-redirect)
• Re-implement redirects (/projects/, /docs/)
• Recreate dynamic sidebar generation
• Add @vuepress/plugin-git for lastUpdated
• Decide on GA: legacy UA vs GA4 snippet
• Integrate search plugin (or disable)
• Integrate sitemap solution
• Confirm meta tags & social previews
• Run dev server & manual QA
• Run production build & diff critical pages
• Update deployment script if necessary
• Update documentation (README + wiki references)
• Remove obsolete files (old theme folder if redundant)
• Open PR for review

Risks / Mitigations

Risk	Impact	Mitigation
Redirects fail	Broken inbound links	Add plugin + test manually
GA UA deprecation	Loss of analytics	Migrate to GA4 immediately
Sidebar structure changes	Navigation confusion	Snapshot existing tree & reproduce
Plugin incompatibility	Build errors	Incremental add & test
Node version drift	CI failure	Update engines + lockfile refresh
Sitemap differences	SEO fluctuations	Validate output & submit updated sitemap

Acceptance Criteria

• All existing docs URLs (excluding known legacy/dead pages) resolve or cleanly redirect.
• Build passes with no VuePress deprecation warnings.
• lastUpdated values display correctly.
• Analytics events confirmed in GA (UA or GA4).
• Changelog, Examples, Docs sections render identically (or minimally changed).
• Deployment script still publishes updated site.

References

• Official Migration Guide: https://vuepress.vuejs.org/guide/migration.html
• VuePress 2 Docs: https://v2.vuepress.vuejs.org/
• Current config: wiki/.vuepress/config.js
• Theme extension: wiki/.vuepress/theme/index.js
• Redirect logic: wiki/.vuepress/enhanceApp.js

Proposed Timeline

Phase	Duration
Audit & Branch	0.5 day
Core Upgrade + Config	1 day
Plugins & Redirects	0.5 day
QA + Adjustments	0.5 day
Documentation & PR	0.5 day

Total: ~2.5–3 days (buffered).

Maintainers

• Lead: (assign on issue creation)
• Reviewer: (assign)
• Analytics Decision: (assign)

---

Please comment if scope adjustments are needed before implementation.