Documentation — GitHub Pages site

[neyec]

Summary

Set up a GitHub Pages documentation site for the Norma project using a static site generator (e.g., MkDocs Material, Docusaurus, or VitePress). The site should be automatically built and deployed from the docs/ directory via GitHub Actions.

Existing docs

The docs/ directory already contains detailed markdown documentation with Mermaid diagrams:

• architecture.md — system overview, ER diagram, LLM integration, data flow diagrams
• api-reference.md — all backend API endpoints with request/response examples
• risk-evaluation.md — dynamic risk classification, decision tree flowchart
• chat-agent.md — Norma agent architecture, system prompt assembly
• document-processing.md — upload pipeline, text extraction, summarisation
• deployment.md — Docker Compose setup, environment variables, startup sequence

These should form the foundation of the site and be extended with additional content below.

Scope

Site setup

• Choose a static site generator with Mermaid diagram support
• Configure navigation, theme, and branding
• Set up GitHub Actions workflow to build and deploy to GitHub Pages on push to main
• Add a link to the docs site in the repo README

Additional content

• Landing page — project overview, key features, screenshots
• Quick start guide — getting running in under 5 minutes
• LLM provider configuration — setup guides for Vertex AI, OpenAI, Anthropic, Azure
• User guide — creating projects, filling the questionnaire, understanding risk levels, uploading documents, using Norma chat, reporting checklist
• Contributing guide — development setup, code style, linting, PR process

Enhancements to existing docs

• OpenAPI/Swagger — embed or link auto-generated API docs from FastAPI
• Screenshots / GIFs — visual walkthrough of key workflows
• Search — full-text search across all documentation pages