---
url: https://docs.rhesis.ai/contribute/managing-docs
title: Managing Documentation
---
# 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

From the repo root:

```bash
./rh dev docs
```

Or manually, from `docs/src`:

```bash
cd docs/src
npm install
npm run dev
```

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

```bash
cd docs/src
npm run build
npm run start
```

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

## Layout

| Location | Role |
| -------- | ---- |
| `docs/src/` | Next.js app: `app/`, `theme.config.jsx`, `mdx-components.js`, `package.json` |
| `docs/content/` | MDX pages and `_meta.tsx` files for navigation |

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 — ``, 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.

See the [Nextra documentation](https://nextra.site/docs) for framework details.