SurfSense/apps/docs/documentation/configuration/docs.mdx

---
title: Documentation config
"og:title": Mintlify setup and configuration
description: Mintlify setup and configuration
---

## Introduction

The documentation site is built entirely using Mintlify. Mintlify docs are rendered from MDX files and configurations. Mintlify works with a Github integration to
constantly build an independent docs site based off your latest published repository.

Documentation can be edited in raw MDX, or directly through the Mintlify dashboard (which stays in sync with your local Github repo).

Mintlify is fast to setup and provides tonnes of features out-the-box without the need to pay for a subscription for the basic services.

You can run the **docs site only** by running the `pnpm run dev` command from a terminal within the `docs` directory.

## Docs structure

The docs root directory is structured as follows:

```
docs
├── _images
├── api
├── configuration
├── deployment
├── logos
├── *.mdx
├── mint.json
└── package.json
```

The docs directory is relatively simple and is made mostly of MDX files. Some notable files are:

| Item         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| api          | Automatically generated files (except for Introduction.mdx) |
| mint.json    | Mintlify configuration object                               |
| package.json | Scripts needed in the monorepo/for generating the API files |

## Creating API endpoint documentation

We can leverage FastAPI's baked in OpenAPI support to automatically generate API documentation.

Using Mintlify's `@mintlify/scraping` package, we can scrape our FastAPI's OpenAPI schema to generate an interactive API documentation site.

<Tip>
  For a more detailed description, read the [official
  documentation](https://mintlify.com/docs/api-playground/openapi/setup#create-mdx-files-for-openapi-endpoints)
</Tip>

### Generating OpenAPI schema

#### Step 1: Generate MDX

Run the `generate-api` scripts within the `package.json` to generate the required MDX
files. There are two scripts here, one configured to use the production
`OpenAPI.json` and the second configured to use the development version.\
\
It is typically preferred to use the production version once any changes to
your API have been made and published.

#### Step 2: Update mint.json

<Steps>
  <Step title="Add new MDX files to navigation">
  Upon generating the relevant API information, `@mintlify/scraping` helpfully outputs the suggested navigation to the terminal:

```bash
navigation object suggestion:
[
  {
    "group": "users",
    "pages": [
      "api/users/get-user",
      "api/users/get-all-users",
      "api/users/search-users",
      "api/users/create-user"
    ]
  },
  {
    "group": "spells",
    "pages": [
      "api/spells/get-spell",
      "api/spells/get-all-spells",
      "api/spells/search-spells"
    ]
  }
]
```

For sake of simplicity, copy this navigation object suggestion and add it your `mint.json` under the `navigation` object:

```json
"navigation": [
  {
    "group": "Getting Started",
    "pages": ["documentation/introduction", "documentation/local-development"]
  },
  {
    "group": "Configuration",
    "pages": [
      "documentation/configuration/turbo",
      "documentation/configuration/fastapi",
      "documentation/configuration/nextjs",
      "documentation/configuration/docs"
    ]
  },
  {
    "group": "Deployment",
    "pages": [
      "documentation/deployment/vercel",
      "documentation/deployment/deployment"
    ]
  },
  {
    "group": "API Reference",
    "pages": ["api/introduction"]
  },
  {
    "group": "Users",
    "pages": [
      "api/users/get-user",
      "api/users/get-all-users",
      "api/users/search-users",
      "api/users/create-user"
    ]
  },
  {
    "group": "Spells",
    "pages": [
      "api/spells/get-spell",
      "api/spells/get-all-spells",
      "api/spells/search-spells"
    ]
  }
],
```

  </Step>
    <Step title="Add OpenAPI endpoint to `mint.json`">
    Add the `openapi` key to your `mint.json`. This, preferably, can be linked to your published OpenAPI schema:

    ```json
    {
      ...
      "openapi":"https://next-fast-turbo-api.vercel.app/openapi.json"
      ...
    }
    ```

    This enables the generated MDX files to describe and interact with your API.

    <Warning>
      This has been hit and miss in the past for me. If doing this does not auto-populate your API reference with the documentation, the solution is to manually\
      create an `openapi.json` file in the `docs` root. Manually copy and paste/save your `openapi.json` into this file.
    </Warning>
    </Step>

</Steps>