Summary
The current GitHub Pages documentation site serves raw markdown files which don't render as HTML. Upgrade to a proper static site generator (Astro recommended) for better user experience.
Current State
deploy-gh-pages.yml creates a simple HTML index with links to .md files- TypeDoc generates API documentation
- Raw markdown files (README.md, CLAUDE.md, DECISIONS.md) are served unrendered
Proposed Solution
Use Astro as the static site generator because:
- Built-in markdown support with frontmatter
- Fast build times and small bundle sizes
- TypeScript-first with excellent DX
- Can integrate TypeDoc output seamlessly
- Supports MDX for interactive documentation
Tasks
References
Summary
The current GitHub Pages documentation site serves raw markdown files which don't render as HTML. Upgrade to a proper static site generator (Astro recommended) for better user experience.
Current State
deploy-gh-pages.ymlcreates a simple HTML index with links to.mdfilesProposed Solution
Use Astro as the static site generator because:
Tasks
docs/site structure with Astrodeploy-gh-pages.ymlto build Astro siteReferences