mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-18 06:43:28 +00:00
22 lines
1.6 KiB
Markdown
22 lines
1.6 KiB
Markdown
# V2 documentation guide
|
|
|
|
## Structure
|
|
|
|
- This directory is a standalone Mintlify site deployed from `packages/docs` on the `dev` branch.
|
|
- Write documentation in MDX. Every page should have `title` and `description` frontmatter.
|
|
- `docs.json` owns site configuration and navigation. Add, move, or remove its page entries whenever the corresponding MDX pages change.
|
|
- Put static files in `assets/` and reference them with root-relative paths such as `/assets/example.svg`.
|
|
- The API endpoint reference is generated by Mintlify from `openapi.json`; do not duplicate endpoint documentation as hand-written MDX.
|
|
- Keep documentation aligned with the V2 packages. Do not use `packages/opencode` as the source of truth unless the task explicitly concerns V1.
|
|
|
|
## Local development
|
|
|
|
- At the start of documentation work, launch `bun dev` from `packages/docs` using the shell tool with `background: true`. Never run the dev server in a foreground shell call and do not poll the process; wait for the background completion notification.
|
|
- Preview the site at `http://localhost:3333`. Mintlify does not expose a host option and binds the preview to all network interfaces. The server reloads changes to MDX and `docs.json` automatically.
|
|
- Use the running preview to verify navigation, links, Mintlify components, code blocks, and desktop and mobile layout.
|
|
|
|
## Validation
|
|
|
|
- Run `bun validate` from `packages/docs` after making documentation or configuration changes.
|
|
- Run `bun broken-links` from `packages/docs` when pages, navigation, headings, or links change.
|
|
- Treat validation errors and broken internal links as blockers. Also verify external links relevant to the change when practical.
|