Support for static site generation (GitHub Pages compatibility) #23
Description
Feature Request: Support for Static Site Generation (GitHub Pages)
Description
Currently, the project requires a running backend/API for searching and real-time diagram rendering. This prevents easy deployment to GitHub Pages. I propose adding an option to generate a fully static version of the site during the build process.
Proposed Changes
- Static Diagram Generation: During the production build, all diagrams should be pre-rendered via a chosen service (local or kroki.io) and saved as static images (PNG/SVG).
- API-to-Static Transition: Update the production build to use these generated images instead of making live API requests.
- Search Handling: Since static hosting doesn't support a backend API, we could either disable the search feature for static builds or implement a lightweight client-side search using a pre-generated JSON index.
Environment Variables
To control the build process, the following environment variables should be introduced:
IS_PROD_STATIC: A boolean flag to toggle the static generation mode during the build.GITHUB_PAGES_REPO_NAME: Used to correctly set base paths for assets, ensuring they load properly when hosted on GitHub Pages (e.g.,https://user.github.io/repo-name/).
Why this is needed
- Student Portfolios: Every student will be able to host their own results using GitHub Pages automatically.
- Easier Grading: Reviewers can check the work via a live link without the need to clone the repository and spin up a local environment.
- Portability: The documentation becomes self-contained and works offline or on any static hosting provider.
Additional Context
By pre-generating assets at build time, we remove the runtime dependency on external diagram servers, making the final output more robust and faster to load.