Hyperion Docs

Developer-first documentation with diagrams-as-code.

This workspace combines Fumadocs v15, Next.js, and Kroki-backed diagram rendering. The default development flow is local-first, so you can run the docs without Docker and avoid rebuilding containers on every change.

Quick Start

Prerequisites

• Node.js 22+
• pnpm 10+

Start Locally

cd LearningPlatformDocs
pnpm install
pnpm dev

Visit http://localhost:3000.

Local development uses hot reload, and diagrams default to the public Kroki instance at https://kroki.io, so Docker is not required.

Stop Local Dev

Press Ctrl+C in the terminal running pnpm dev.

Optional Docker Flow

If you want the full containerized stack with a self-hosted Kroki service:

cd LearningPlatformDocs
pnpm dev:docker

To stop it:

cd LearningPlatformDocs
pnpm stop:docker

Useful Scripts

• pnpm dev - start the docs app locally with Next.js hot reload
• pnpm dev:docker - start the Docker-based docs + Kroki stack
• pnpm build:openapi - regenerate OpenAPI-derived docs content
• pnpm lint - run workspace linting
• pnpm typecheck - run workspace type checking

Environment

The docs app supports these environment variables:

• KROKI_BASE_URL - Kroki server URL. Defaults to https://kroki.io.
• API_RES_PATH - directory used for OpenAPI resources. Defaults to openapi.
• IS_PROD_STATIC - enable static export mode when set to true.
• GITHUB_PAGES_REPO_NAME - repository name used for GitHub Pages base paths.

If you want to run your own Kroki locally without Docker Compose, set:

KROKI_BASE_URL=http://localhost:8000

Project Structure

LearningPlatformDocs/
|-- apps/
|   `-- docs/              # Next.js + Fumadocs app
|-- scripts/               # Docker helper scripts
|-- docker-compose.dev.yml # Optional docs + kroki stack
`-- package.json           # Workspace scripts

Troubleshooting

Diagrams do not render

1. Check that KROKI_BASE_URL points to a reachable Kroki server.
2. If you are using the default public endpoint, verify outbound network access.
3. Confirm the diagram language exists in LANG_MAP inside apps/docs/src/app/api/diagram/route.ts.

TypeScript issues

cd LearningPlatformDocs
pnpm typecheck