> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensource-together.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Contribute to the docs
> Run this documentation site locally, and keep the API reference in sync
These pages live in the [`ost-docs`](https://github.com/opensource-together) repository and are
built with [Mintlify](https://mintlify.com). Fixing a confusing paragraph is a perfectly good
first contribution.
## Run the docs locally
**Prerequisites:** Node.js 19 or higher.
```bash theme={null}
npm i -g mint
```
From the repository root, where `docs.json` lives:
```bash theme={null}
mint dev
```
Your local preview runs at [http://localhost:3000](http://localhost:3000).
To use a different port:
```bash theme={null}
mint dev --port 3333
```
## How the site is organised
| Path | Contents |
| ----------------------------- | ---------------------------------------------------------------------------- |
| `docs.json` | Navigation, theme, and site configuration. New pages must be registered here |
| `index.mdx`, `quickstart.mdx` | The Guides tab entry points |
| `contributing/` | Contribution, Learn-content, and deployment guides |
| `web-app/` | Web app architecture, features, and development guides |
| `api-reference/` | The generated API reference (see below) |
| `ai/` | AI Engine documentation |
| `images/`, `logo/` | Static assets |
A page that isn't listed in `docs.json` won't appear in the navigation, even if the file
exists.
## Updating the API reference
The API reference is generated. **Never edit `api-reference/openapi.json` or the endpoint
pages by hand.** The source of truth is the API's own Swagger output.
```bash theme={null}
curl -s https://api.opensource-together.com/api-docs-json | python3 -m json.tool --indent 2 > api-reference/openapi.json
```
Then regenerate the endpoint pages:
```bash theme={null}
npx @mintlify/scraping@latest openapi-file api-reference/openapi.json -o api-reference/endpoint
```
Each endpoint page is a three-line stub that points Mintlify at an operation in the spec:
```mdx theme={null}
---
openapi: get /users/me/bookmarks
---
```
Finally, register any newly generated page in the `API Reference` tab in `docs.json`. The
scraper writes files but doesn't touch navigation.
`/api/auth/*` (better-auth) is deliberately absent from the specification. The API's
generator doesn't see those routes. They're documented by hand in
[the API introduction](/api-reference/introduction), so keep that page in mind when auth
changes.
## Before you open a pull request
Check that nothing links into a void:
```bash theme={null}
mint broken-links
```
## Writing conventions
* Prefer showing the real command or file path over describing it.
* Don't document intentions. If the code doesn't do it yet, don't write it down.
* When a convention has exceptions in the codebase, say so; contributors will find them anyway.
* Use ``, `` and `` for genuine caveats, not for emphasis.
## Troubleshooting
Usually an outdated Node version:
1. `npm remove -g mint`
2. Upgrade to Node 19 or higher.
3. `npm i -g mint`
Make sure you're running `mint dev` from the folder containing `docs.json`, and that the
page is registered in the navigation.
Delete the `~/.mintlify` folder and run `mint dev` again.
## Deployment
Changes merged to the default branch deploy automatically through the Mintlify GitHub app.
