Documentation System

Documentation System

KoAkademy enforces a single-source documentation workflow:

1. Root Markdown files are canonical for foundational technical documents (installation, deployment, architecture, contributing, troubleshooting).
2. The Astro Starlight documentation website and the in-app docs viewer consume automatically generated MDX mirrors.
3. Specialized guides (System Internals, Maintainers, User Guides, Enrollment Blueprints, API Reference) are native MDX files authored directly under docs/src/content/docs/.

Architecture & Sync Pipeline

Canonical Root Docs (e.g. CONTRIBUTING.md)
   │
   ├──▶ npm run docs:sync (scripts/sync-docs.mjs)
   │       └── Generates MDX mirrors with frontmatter & warning headers
   │
   └──▶ npm run docs:check (scripts/check-docs.mjs)
           ├── Validates mirrors are up to date
           ├── Checks that internal links resolve correctly
           └── Verifies API contract documentation

Mapping of Canonical Files to Generated Mirrors

Canonical Root File	Generated Site Mirror	Sidebar Placement
GETTING_STARTED.md	docs/src/content/docs/self-hosting/installation.mdx	Self-Hosting → Installation
DEPLOYMENT.md	docs/src/content/docs/self-hosting/deployment.mdx	Self-Hosting → Deployment
CONFIGURATION.md	docs/src/content/docs/self-hosting/configuration.mdx	Self-Hosting → Configuration
TROUBLESHOOTING.md	docs/src/content/docs/self-hosting/troubleshooting.mdx	Self-Hosting → Troubleshooting
FAQ.md	docs/src/content/docs/self-hosting/faq.mdx	Self-Hosting → FAQ
DEVELOPMENT.md	docs/src/content/docs/start-here/development.mdx	Start Here → Development
ARCHITECTURE.md	docs/src/content/docs/start-here/architecture.mdx	Start Here → Architecture
CONTRIBUTING.md	docs/src/content/docs/start-here/contributing.mdx	Start Here → Contributing

Never Edit Generated Mirrors Directly

Generated MDX mirror files contain a {/* GENERATED FILE. Source: ... */} header. Any manual edits to generated files will be overwritten by npm run docs:sync and will fail the CI check npm run docs:check. Always edit the root canonical Markdown file instead.

Decision Table: Where to Write New Documentation

If you are writing…	Edit this location	Workflow
Setup, installation, or server deployment	GETTING_STARTED.md or DEPLOYMENT.md	Edit root file ➔ run npm run docs:sync ➔ commit both
Environment variables or service config	CONFIGURATION.md	Edit root file ➔ run npm run docs:sync ➔ commit both
Contributor workflows, testing rules, setup	CONTRIBUTING.md or DEVELOPMENT.md	Edit root file ➔ run npm run docs:sync ➔ commit both
High-level runtime or architecture overview	ARCHITECTURE.md	Edit root file ➔ run npm run docs:sync ➔ commit both
Deep system internals (auth, frontend, queues)	docs/src/content/docs/system/*.mdx	Edit native MDX directly
Module development or maintainer processes	docs/src/content/docs/maintainers/*.mdx	Edit native MDX directly
User and staff operational guides	docs/src/content/docs/user-guide/*.mdx	Edit native MDX directly
Enrollment blueprint engine guides	docs/src/content/docs/enrollment-policies/*.mdx	Edit native MDX directly
Public REST API reference	docs/src/content/docs/api/*.mdx	Edit native MDX directly

Running Local Verification

Always run the full documentation verification before pushing:

# 1. Sync any canonical changes to their mirrors
npm run docs:sync

# 2. Check for stale mirrors and broken internal links
npm run docs:check

# 3. Test the Astro production build locally
npm --prefix docs run build

Documentation Website Stack

• Framework: Astro 5 with @astrojs/starlight and @astrojs/mdx.
• Search: Built-in client-side Pagefind indexing.
• Typography & Styling: Self-hosted @fontsource/inter and @fontsource/jetbrains-mono with custom CSS matching the application’s shadcn/ui palette (docs/src/styles/custom.css).
• Sidebar Navigation: Configured explicitly in docs/astro.config.mjs.
• In-App Integration: The same generated documentation files are rendered inside the running application at /docs.

Automated Deployment (GitHub Pages)

The documentation site is automatically built and deployed to GitHub Pages on documentation changes merged into master via .github/workflows/deploy-docs.yml.

When deploying:

1. Ensure GitHub Pages is configured with Source: GitHub Actions in repository settings.
2. The site publishes to https://yukazakiri.github.io/koakademy/.