How-to for Frontend Docs
Hand-written guides for the frontend, authored as regular Docusaurus MDX.
These pages live in docs/ and are served under /docs. They are completely
separate from the Backend API reference, which is generated from an
OpenAPI specification and served under /api.
How the two sections differ
| Frontend docs | Backend API docs | |
|---|---|---|
| Route | /docs | /api |
| Source | docs/**/*.mdx, written by hand | openapi/backend.yaml, generated |
| Sidebar | sidebars.ts | sidebarsApi.ts + generated slice |
| Doc component | Docusaurus default | @theme/ApiItem |
Because they are two independent plugin-content-docs instances, MDX features
here are unaffected by the OpenAPI theme, and regenerating the API reference
never touches these files.
Writing a page
Add an .mdx file anywhere under docs/. The sidebar is autogenerated from the
folder structure, so a new file shows up without any config change:
docs/guides/my-page.mdx
---
sidebar_position: 2
---
# My Page
Ordinary MDX. Import components, use admonitions, whatever you need.
tip
Use _category_.json inside a folder to control its sidebar label and position.