Managing Documentation

How to run, extend, and maintain the Rhesis docs site (Nextra + Next.js). Source lives under docs/; MDX content is in docs/content/.

Run the site

Recommended — from the repo root:

./rh dev docs

That runs docs/src/start.sh (installs dependencies if needed, then npm run dev).

Manual — from docs/src:

cd docs/src
npm install
npm run dev

Open http://localhost:3001 . Production build and run:

cd docs/src
npm run build
npm run start

Port in use: PORT=3002 npm run dev (still under docs/src).

Layout

Add a new page by creating a .mdx file under the right folder (for example docs/content/contribute/...) and, if you need a new nav entry, update the nearest _meta.tsx.

MDX essentials

• Curly braces: In MDX, {...} is treated as JSX. In normal text, escape placeholders: \{id\}, \{userId\}. Fenced code blocks and inline backticks do not need escaping.
• Components: Use project patterns — <Callout>, fenced code with a language, and shared JSX from docs/src/components/ registered in mdx-components.js. Do not import @mui/icons-material/* directly in .mdx; wrap icons in a small component and register it (same pattern as other docs pages).

Search (Pagefind)

Full-text search is powered by Pagefind and is available after a production build, not only in dev. npm run build in docs/src runs the postbuild step that indexes the site into public/_pagefind/.

If search looks wrong or empty, rebuild from docs/src and confirm public/_pagefind/ exists.

Troubleshooting

• Build or MDX errors: Fix syntax, resolve bad imports, and check for unescaped { in prose outside code fences.
• Dependencies: From docs/src, try rm -rf node_modules package-lock.json && npm install.
• Stale Next cache: rm -rf .next in docs/src, then npm run dev again.