A scalable, serverless documentation platform demonstrating modern Static Site Generation (SSG) and Automated Content Aggregation. This project serves as a reference architecture for centralized knowledge management, leveraging VitePress (Vue.js) for high-performance frontend delivery and a custom Python ETL pipeline for dynamic content ingestion from distributed repositories.
Hosted on GitHub Pages with fully automated CI/CD pipelines, ensuring high availability, zero-maintenance infrastructure, and rapid content delivery.
Frontend: VitePress (Vue 3 + Vite) for lightning-fast static site generation and SEO optimization. Content Pipeline: Custom Python-based ETL (Extract, Transform, Load) system that aggregates READMEs and metadata from multiple GitHub repositories into a unified portal. Infrastructure: Serverless deployment via GitHub Pages. CI/CD: GitHub Actions for automated build, test, and deployment workflows.
Automated Content Aggregation: Centralizes documentation from disparate microservices/projects into a single source of truth. High Performance: Pre-rendered static HTML with client-side hydration for SPA-like navigation. Developer Experience (DX): Markdown-centric workflow with hot module replacement (HMR) for rapid iteration. Scalability: Stateless architecture capable of handling high traffic loads via CDN distribution.
This project utilizes a Nix Flake and direnv to manage a fully declarative development environment. This ensures that Node.js, Python (with libraries), and ImageMagick are automatically provisioned and kept consistent across all machines and CI/CD.
If you don't have them installed:
Once installed, simply cd into the project directory and allow the environment:
direnv allowThe environment will automatically load:
- Node.js 22
- Python 3 (pre-configured with
pyyamlandrequests) - ImageMagick (for local image processing)
- Ruff (for linting)
npm installExecutes the Python pipeline to fetch and transform remote documentation into local Markdown resources.
npm run docs:generateGenerates and processes splat-related assets.
npm run docs:generate-splatsStarts the VitePress development server with hot-reload capabilities.
npm run docs:devCompiles the application into static assets optimized for production deployment.
npm run docs:buildLocally preview the production build to verify rendering and behavior.
npm run docs:previewContinuous Deployment is managed via GitHub Actions executing inside a Nix environment. Commits to the main branch trigger the deploy workflow, which ensures the production build environment exactly matches the local development state.
- Request Manifests: Content sources are defined in
requests/*.yaml. - Output Structure: Generated Markdown files are organized into the
projects/folder