minmoto/docs repository overview

⁠Minmo Docs

Public developer documentation at https://docs.minmo.to, built with Astro Starlight. Starlight owns responsive navigation, search (Pagefind), code blocks, heading links, and themes. There is no authentication or runtime API credential.

⁠Development

From the repository root:

npm install
npm run dev:docs
npm run build:docs
npm run test:docs

Development runs at http://localhost:3005. Use docker compose up docs for container development. npm run start --workspace=@minmo/docs previews a build. Pagefind search and the llms plugin's output are generated during the build; use preview to verify them. Individual Markdown routes also work in development.

⁠Content and agent exports

Edit src/content/docs/**/*.md and the sidebar in astro.config.mjs. Keep guides in plain Markdown so their per-page exports are complete without a UI runtime. Starlight's component overrides only add navigation, export links, and brand colors from @minmo/theme. The API surface is intentionally not rendered inside the docs app: Use API opens the environment's live OpenAPI document from the API service.

• /markdown/<page>.md: the same collection content as the HTML guide.
• /markdown/index.json: discoverable list of per-page exports.
• /llms.txt, /llms-full.txt, /llms-small.txt: generated by starlight-llms-txt, an upstream Starlight plugin.
• /build-with-ai/: copy-ready instructions for coding agents.
• /openapi.json: an environment-aware redirect to the API service's live OpenAPI document.

The app pins the public @minmoto/sdk release. Tests compile every ts fenced example against that package without sending live requests. Update the package pin, guide version labels, and examples together when adopting a new release. Method-level TypeDoc generation is not included in this first app; the guide links to the public SDK and its exported declarations.

⁠Deployment

The build emits a static dist/ directory, including search and agent exports. Publish the whole directory to a static host at docs.minmo.to, or build the root-context Dockerfile and serve its unprivileged Nginx image on port 8080. The publish workflow builds an image using the existing repository credentials. The Terraform services stack deploys that image as the docs Compose service, routes docs.[environment.]minmo.to through Traefik, and terminates HTTP at HTTPS. DNS records still need to point the environment hostname at the services VM.

Console links to docs.[environment.]minmo.to using its existing environment mapping. The old Console docs routes are removed without redirects. The docs app does not copy or render the API schema; its environment-aware /openapi.json route redirects to the API service's live /spec document.

⁠Environment configuration

NEXT_PUBLIC_APP_ENV uses the same development, staging, and production values as Console. The default hostname prefixes are dev., staging., and empty respectively. With no environment supplied, production is used.

NEXT_PUBLIC_API_URL is accepted from the existing image-build workflow. For local Astro development, PUBLIC_API_URL overrides it and PUBLIC_DOCS_URL overrides the docs origin. Copy .env.example to .env for local endpoints. These are public build-time settings; rebuild when changing environments. The live-spec link, canonical URLs, and AI index use the configured environment. The SDK itself still defaults to production; integrations targeting another deployment must explicitly set baseUrl.