Evaluate modern framework options for the website

[tgrall]

Context

The website currently uses Docusaurus 2.4.x, React 17, MDX 1, and a GitHub Pages workflow pinned to Node 16. The project is primarily a personal blog and content site rather than a documentation portal.

The goal is to evaluate a more modern, maintainable framework without making implementation changes yet.

Current project assessment

• 275 blog posts, all with frontmatter
• 11 mostly starter documentation files
• 7 custom React components/pages
• 113 static assets (approximately 16 MB)
• 68 posts contain some raw HTML
• 154 older posts use categories; newer posts generally use tags
• 7 posts import react-gist
• 1 recent MDX post uses Docusaurus Tabs and an admonition
• The showcase page is the only substantial client-side interactive feature
• All 288 Markdown/MDX documents pass the official Docusaurus MDX 3 compatibility checker

Current maintenance issues

• The current build fails on Node 26 because the old Webpack toolchain relies on legacy OpenSSL behavior.
• GitHub Actions uses end-of-life Node 16 and old action versions.
• Docusaurus is several releases behind the current 3.10.2 version.
• Both package-lock.json and yarn.lock are committed while CI uses npm.
• The homepage reads an internal generated Docusaurus JSON file from .docusaurus/.
• Google Analytics still uses a retired Universal Analytics UA-* identifier.
• Default Docusaurus tutorial documentation remains in the repository.

Options

Option	Project fit	Migration effort	Ongoing maintenance	Interactive content	Assessment
Astro 7	Excellent	Medium	Low	Excellent, opt-in	Best replacement
Docusaurus 3	Good	Low	Medium	Excellent	Best low-risk path
Eleventy 3	Very good	Medium	Very low	Manual	Strong minimalist choice
Hugo 0.164	Very good	Medium-high	Very low	Manual	Strong non-Node choice
Next.js 16	Fair	High	Medium-high	Excellent	Not recommended

Option 1: Astro 7

Astro is the strongest architectural fit because it is designed for content-driven sites and emits static HTML by default while allowing JavaScript only where needed.

Advantages

• Typed, validated content collections for the evolving frontmatter model
• Official Markdown, raw HTML, MDX, React, and GitHub Pages support
• Existing React showcase can remain an interactive island
• Little or no client-side JavaScript on normal blog pages
• Public content APIs for recent posts, archives, tags, and related content
• Good support for RSS, sitemaps, syntax highlighting, and image processing

Migration considerations

• Preserve /blog/YYYY/MM/DD/slug routes exactly
• Define a schema accepting legacy categories and modern tags
• Create blog index, archive, tag, pagination, and feed templates
• Replace seven react-gist usages and the Docusaurus Tabs/admonition
• Port the homepage, static pages, and showcase
• Validate the 68 raw-HTML posts against Astro 7's stricter compiler

Assessment: Best long-term architecture and recommended replacement.

Option 2: Upgrade to Docusaurus 3

This is the lowest-risk route and should remain the baseline against which a rewrite is justified.

Advantages

• Existing routes, components, blog behavior, tags, pagination, feeds, and theme remain largely intact
• All content already passes the official MDX 3 compatibility checker
• No need to recreate standard blog functionality
• Smallest visual and behavioral change

Required work

• Upgrade Docusaurus, React, MDX, and Prism dependencies together
• Replace the homepage's internal generated-JSON dependency
• Modernize GitHub Pages deployment and Node LTS
• Select one package manager and lockfile
• Replace or remove Universal Analytics
• Remove unused starter documentation if appropriate
• Visually verify raw HTML and embedded Gists

Assessment: Best risk-to-effort ratio if the objective is maintenance recovery rather than architectural simplification.

Option 3: Eleventy 3

Eleventy offers a small API, minimal browser JavaScript, and a low dependency surface.

Advantages

• Excellent Markdown, raw HTML, layout, and frontmatter support
• Straightforward static output and GitHub Pages deployment
• Simple architecture that should remain understandable over time

Tradeoffs

• More custom work for archives, tags, pagination, feeds, and navigation
• MDX/React integration is less central than in Astro
• Gists and tabs should become shortcodes or web components
• Showcase interactivity needs explicit client-side JavaScript
• Less integrated content validation than Astro

Assessment: Strong choice when minimal dependencies are the highest priority.

Option 4: Hugo 0.164

Hugo is mature, extremely fast, and distributed as a single executable.

Advantages

• Very fast builds
• No Node runtime unless needed for the asset pipeline
• Mature taxonomies, RSS, syntax highlighting, image processing, and URL controls
• Very low operational burden after migration

Tradeoffs

• Go templates introduce a new development model
• Existing React components cannot be reused directly
• Gists, tabs, and admonitions need Hugo shortcodes
• Showcase requires separate JavaScript
• Theme customization may create theme-specific coupling

Assessment: Strong option when avoiding the Node ecosystem is more important than migration simplicity.

Option 5: Next.js 16

Next.js supports static export and GitHub Pages but is application-oriented rather than content-oriented.

It would require additional content tooling and expose the site to unnecessary React/application framework complexity. Static export also supports only a subset of Next.js features.

Assessment: Not recommended unless the website is expected to become a substantial web application.

Excluded options

• Gatsby: Excessive build and plugin complexity
• VitePress/Nextra: Documentation-first rather than blog-first
• Jekyll: Does not offer a compelling modernization over the current stack
• Hosted CMS: Unnecessary unless browser-based, nontechnical editing becomes a requirement

Recommendation

1. Choose Astro if the objective is a cleaner long-term architecture, typed content, reduced JavaScript, and easier redesigns.
2. Choose Docusaurus 3 if the objective is to restore maintainability with the least migration risk and effort.
3. Consider Eleventy for maximum simplicity or Hugo for minimum runtime dependency.

Proposed migration sequence

1. Capture all currently published URLs, metadata, feeds, and representative rendered pages.
2. Normalize categories and tags into one taxonomy model while preserving aliases.
3. Establish regression fixtures for old, HTML-heavy, Gist-based, and recent MDX posts.
4. Preserve /blog/YYYY/MM/DD/slug routes and the existing redirect.
5. Migrate the layout, homepage, static pages, and blog templates.
6. Convert the eight component-dependent posts.
7. Port the interactive showcase.
8. Compare generated routes, links, metadata, RSS, and rendered output.
9. Switch to GitHub's official Pages artifact deployment workflow.

Decision needed

Select between:

• Astro migration: medium initial effort, best architectural fit
• Docusaurus 3 upgrade: low initial effort, lowest migration risk