[Enhancement] Migrate Documentation from MkDocs to Docusaurus

[flexykrn]

Summary

The current XDCDocs website is built on MkDocs Material. While functional, the UI lacks the modern interactivity, responsiveness, and developer experience expected by blockchain documentation standards (Ethereum, Solana, Polygon all use Docusaurus).

Proposal

Migrate the entire documentation site from MkDocs Material to Docusaurus v3 to achieve:

• Modern, responsive design with better mobile support
• MDX support — embed React components, live code demos, interactive widgets
• Built-in versioning — critical for mainnet/testnet/devnet documentation
• Algolia DocSearch — superior search experience vs current lunr.js
• i18n support — foundation for multi-language docs
• Full React ecosystem — custom components for wallet demos, RPC endpoints, network selectors
• Self-hosted — full control over build, deployment, and domain

Scope

• Content: 167 Markdown files across Learn, XDC Chain, Subnet, Enterprise, API, Announcements
• Assets: All images, logos, diagrams, downloads (~71MB)
• Navigation: Full nested sidebar (7 top-level sections, 50+ subsections)
• Branding: Preserve XDC dark mode, custom colors, logo, favicon
• Features: Search, code copy, dark/light toggle, GitHub edit links, external links
• Deployment: GitHub Actions → GitHub Pages (docs.xdc.network)

Technical Details

Aspect	Current (MkDocs)	Target (Docusaurus)
Generator	MkDocs (Python)	Docusaurus v3 (React/Node)
Theme	Material	Classic (customized)
Content Format	Markdown	MDX (Markdown + JSX)
Search	lunr.js (local)	Algolia DocSearch
Versioning	Plugin-based	Built-in
i18n	Plugin-based	Built-in
Custom Components	Limited (HTML)	Full React components
Build Output	Static HTML	Static HTML (React SSR)
Deployment	GitHub Actions	GitHub Actions
Hosting	GitHub Pages	GitHub Pages

Content Migration Checklist

Item	Status	Notes
Admonitions (!!! → :::)	⬜	Note, warning, tip, danger, info
Content tabs (=== → <Tabs>)	⬜	Code examples, platform-specific
Image paths (assets/ → /assets/)	⬜	All 71MB of images
Internal links (.md → Docusaurus path)	⬜	167 files, cross-references
Anchor links (#Heading → #heading)	⬜	Lowercase, dash-separated
Code blocks (add language tags)	⬜	Solidity, JavaScript, Bash, JSON
Frontmatter (add sidebar_position, title)	⬜	Key index pages
External links (verify, add target="_blank")	⬜	Faucet, explorer, ecosystem
MkDocs macros/plugins	⬜	Convert to React or static
Table of contents (auto-generated)	⬜	Docusaurus built-in

Custom Components to Build

Component	Purpose	Priority
NetworkSelector	Switch between Mainnet/Testnet/Devnet	High
RPCEndpoint	Display RPC URL with copy button	High
ContractVerifier	Link to explorer with pre-filled data	Medium
FaucetButton	Direct link to faucet with network param	Medium
CodeSandbox	Embed live code examples	Low
MermaidDiagram	Architecture diagrams (already supported)	Medium

Performance Targets

Metric	Target	Current (Estimated)
First Contentful Paint (FCP)	< 1.5s	~2s
Largest Contentful Paint (LCP)	< 2.5s	~3s
Time to Interactive (TTI)	< 3.5s	~4s
Cumulative Layout Shift (CLS)	< 0.1	~0.05
Total Bundle Size	< 500KB	~600KB
Lighthouse Performance	> 80	~70
Lighthouse Accessibility	> 90	~85

SEO & Analytics

• Sitemap generation (docusaurus-plugin-sitemap)
• robots.txt configuration
• Canonical URLs for all pages
• OpenGraph meta tags (title, description, image)
• Twitter Card meta tags
• JSON-LD structured data for docs
• Google Analytics / Plausible integration (if currently used)

Accessibility Requirements

• WCAG 2.1 AA compliance
• Keyboard navigation for all interactive elements
• Screen reader friendly (ARIA labels, landmarks)
• Color contrast ratio > 4.5:1 for text
• Alt text for all images
• Focus indicators visible
• Skip-to-content link

Testing Plan

Test	Method	Pass Criteria
Build	npm run build	Zero errors, zero warnings
Links	npm run build + manual	No broken internal links
Mobile	Chrome DevTools (iPhone SE, Pixel 5)	Readable, nav accessible
Tablet	Chrome DevTools (iPad)	Sidebar visible, readable
Desktop	Chrome, Firefox, Safari	Layout correct, all features work
Accessibility	axe DevTools + Lighthouse	0 critical issues, >90 score
Performance	Lighthouse CI	>80 performance, <2.5s LCP
Search	Manual test	Returns relevant results
Dark mode	Toggle + system preference	Renders correctly, persists
Code copy	Click copy button	Copies to clipboard
Edit links	Click "Edit this page"	Opens GitHub edit view
External links	Click external links	Opens in new tab, correct URL

Rollback Plan

Scenario	Action	Time to Recover
Build fails on main	Revert commit, restore mkdocs.yml	< 5 min
Deployment broken	Switch GitHub Pages source to old branch	< 5 min
Critical bug post-merge	Hotfix branch from last MkDocs commit	< 15 min
Full migration rejected	Keep docusaurus-migration branch, continue MkDocs	Immediate

Rollback protection:

• mkdocs.yml → mkdocs.yml.legacy (preserved)
• requirements.txt → requirements.txt.legacy (preserved)
• run.sh → run.sh.legacy (preserved)
• Old GitHub Actions workflow preserved until verified

Migration Plan

Phase	Tasks	Time
1. Scaffold	Init Docusaurus v3, config, branding, theme	~30 min
2. Content Migration	Copy all MD files, fix MDX syntax, sidebar, links	~2-3 hrs
3. Build & Verify	Fix broken links, MDX errors, missing assets	~1-2 hrs
4. Polish & Deploy	Algolia search, custom components, CI/CD	~1 hr
5. Merge & Switchover	Archive MkDocs, merge to main	~30 min

Total estimated effort: 5-7 hours

Competitor Benchmark

Platform	Used By	Self-Hosted	Customization	Best For
Docusaurus	Ethereum, Solana, Polygon, Supabase	✅ Yes	Full React	Blockchain/technical docs
GitBook	SaaS products	❌ No (SaaS lock-in)	Limited templates	Non-technical teams
Mintlify	Figma, Cursor, Linear	❌ No (Enterprise only)	Moderate	API-first startups

Acceptance Criteria

Content

• All 167 pages render correctly in Docusaurus
• Navigation matches current MkDocs structure (7 sections, 50+ subsections)
• XDC branding (dark mode, colors, logo, favicon) preserved
• All images and static assets load correctly
• All internal links functional (no 404s)
• All external links open correctly in new tabs
• Code blocks have syntax highlighting (Solidity, JS, Bash, JSON)
• Admonitions (note, warning, tip, danger) render correctly
• Content tabs (platform-specific code) render correctly
• Table of contents auto-generated for all pages
• Anchor links functional (lowercase, dash-separated)
• GitHub "Edit this page" links correct

Functionality

• Search returns relevant results (Algolia or local fallback)
• Dark mode default, light mode toggle works
• Code copy button functional
• Mobile responsive (tested on iPhone SE, Pixel 5, iPad)
• Tablet layout correct (sidebar visible)
• Desktop layout correct (full navigation)

Build & Deploy

• Clean build with zero errors and zero warnings
• GitHub Actions auto-deploys to docs.xdc.network
• CNAME preserved (docs.xdc.network)
• Build time < 3 minutes

SEO & Performance

• Sitemap generated and submitted
• OpenGraph meta tags on all pages
• Lighthouse Performance score > 80
• Lighthouse Accessibility score > 90
• First Contentful Paint < 1.5s
• Largest Contentful Paint < 2.5s

Documentation & Rollback

• README updated with Docusaurus build instructions
• MkDocs legacy files archived (not deleted)
• Rollback procedure documented and tested
• No regression in page load time vs MkDocs

Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
Build breaks during migration	Medium	High	Branch isolation (docusaurus-migration), verify at every step
MDX syntax errors on complex pages	High	Medium	Fix iteratively, test build after each batch
Missing assets/images	Medium	Medium	Systematic copy + build verification
Broken internal links	High	Medium	Automated find/replace + manual review
Algolia approval delay	Medium	Low	Local search fallback until approved
Performance regression	Low	Medium	Lighthouse CI, bundle analysis
Accessibility issues	Medium	Medium	axe DevTools, WCAG checklist
Rollback needed	Low	High	Keep mkdocs.yml.legacy, 5-min rollback

Next Steps

1. Create docusaurus-migration branch
2. Execute migration plan (can be done in a single focused session)
3. Visual verification by maintainers
4. Merge to main, archive MkDocs

---

Labels: enhancement, documentation
Priority: Medium-High (improves developer onboarding experience)
Effort: ~1 day (can be parallelized across contributors)