Overview
How the documentation portal works and how to contribute.
What is this?
The documentation portal is a centralised place for all Holibob service documentation. It is a Next.js 16 application deployed on AWS Amplify and serves both internal (developer-facing) and external (consumer-facing) documentation.
How it works
Each service in the monorepo can publish documentation by adding a docs/ directory with:
- A
docs.config.ts— declares the service name, sidebar label, icon, and sort order. - One or more
.mdfiles — each with YAML front-matter that controls title, description, ordering, and audience visibility.
At build time, a discovery script scans for docs.config.ts files, reads the accompanying markdown, and generates sidebar navigation automatically. No manual wiring required.
Audience model
Every markdown file has an audience front-matter field:
| Value | Who sees it | Default |
|---|---|---|
internal | Developers only (when developer mode is on) | Yes |
external | Everyone | No |
Defaulting to internal means new docs are hidden from external consumers until explicitly opted in — the safe choice.
The developerOnly flag is a separate toggle. When set to true, the page is only visible when developer mode is enabled, regardless of audience.
Developer mode
Click the avatar in the top-right corner and toggle Developer mode to reveal internal-only pages. A yellow "Developer" badge and amber avatar ring indicate when the mode is active.