> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Mintlify

> How docs.json's modular $ref-linked config works, what lives in each config/ file, and how to edit navigation without touching a monolithic file.

`docs.json` is the root of every Mintlify setting for this site - theme, fonts, navigation, redirects, and more. It used to be a single 21,000+ line file. Its two largest pieces, `navigation` and `redirects`, are now split out into their own files under `config/`, using Mintlify's [split-configuration `$ref` support][1]. This page covers how that split works and where to make a given change. For redirect-specific guidance, see [Redirects and redirect\_from][2].

## What lives where

```json theme={null}
docs.json                          # theme, fonts, navbar, footer, and $ref pointers for navigation + redirects
config/
  navigation.json                  # languages[] shell + global.anchors
  redirects.json                   # the full redirects array
  nav-en.json                      # English tabs; several of them are further $ref'd out below
  nav-da.json / nav-de.json / nav-nl.json / nav-no.json / nav-sv.json
  nav-learn.json                   # Guides tab's groups
  nav-mobile.json                  # Mobile tab's groups
  nav-integrations.json            # Integrations tab's groups
  nav-online.json                  # CRM Platform tab's pages
  nav-onsite.json                  # Onsite tab's pages (hidden: true, searchable: true)
  nav-releases.json                # Release Notes tab's groups
  nav-api.json                     # Developer guide > API item's groups
  nav-restful-agent-openapi.json   # Developer guide > API > Web Services > Reference > HTTP RPC Agent API > Operations (generated)
  nav-restful-rest-openapi.json    # Developer guide > API > Web Services > Reference > RESTful REST API > Operations (generated)
  nav-database-tables.json         # Developer guide > Database > Reference group's pages (generated)
  nav-archive-providers.json       # Developer guide > API > Search APIs > Archive provider reference group's pages (generated)
  nav-mdo-providers.json           # Developer guide > API > Search APIs > MDO provider reference group's pages (generated)
  nav-crmscript-ref.json           # Developer guide > CRMScript Reference item's pages
  nav-contribute.json              # Contribute tab's pages
```

## How `$ref` resolves

Any key's value can be replaced with an object holding a `$ref`:

```json theme={null}
"navigation": {
  "$ref": "./config/navigation.json"
}
```

Two rules matter once you're editing these files directly:

* **Relative paths resolve against the file that contains them, not against `docs.json`.** `config/navigation.json`'s `"tabs": {"$ref": "./nav-en.json"}` means `./config/nav-en.json` relative to `docs.json`, because the ref lives inside `navigation.json`, not inside `docs.json` itself.

* **Sibling keys next to a `$ref` merge on top of the resolved value, but only if it resolves to an object.** If it resolves to an array (every ref in this repo's nav/redirects split does), sibling keys are ignored - which is why `"language": "da"` stays outside the `$ref` as a sibling of `"tabs"`, not inside it.

<Note>
  Refs can chain - a file you land in after following one `$ref` can contain its own. Following `docs.json` -> `config/navigation.json` -> `config/nav-en.json` -> `config/nav-mobile.json` is four files, three hops.
</Note>

## Modular navigation

`navigation` splits in two stages. First, each language's `tabs` array moves to its own `config/nav-<lang>.json`, leaving only `{"language": ..., "tabs": {"$ref": ...}}` in `config/navigation.json`. Second, within English specifically, every large or frequently-edited tab and Developer-guide menu item is `$ref`'d one level further into its own file: Guides (`nav-learn.json`), Mobile, Integrations, CRM Platform, the hidden Onsite tab, Release Notes, Contribute, and Developer guide's API and CRMScript Reference items (`nav-api.json`, `nav-crmscript-ref.json`). Machine-generated reference trees go a level deeper still - `nav-database-tables.json`, `nav-archive-providers.json`, `nav-mdo-providers.json`, and the two OpenAPI-derived operation lists nested inside `nav-api.json` (`nav-restful-agent-openapi.json`, `nav-restful-rest-openapi.json`) are all regenerated by their respective pipelines, not hand-edited. Only Home stays fully inline in `nav-en.json` itself.

## Editing navigation

Find the right file before editing:

| Change                                                                                               | File                                                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add/edit a page in a non-English language's existing tab                                             | `config/nav-<lang>.json`                                                                                                                                                      |
| Regenerate a whole non-English language's nav from `toc.yml`                                         | `tools/migration/update-docs-navigation.ps1` (writes `config/nav-<lang>.json` directly; refuses `en`)                                                                         |
| Fill in or insert a menu item's `groups` (any language, including English tabs not split further)    | `tools/splice-nav-groups.py` against the relevant `config/nav-<lang>.json`                                                                                                    |
| Edit Mobile, Integrations, or Release Notes content                                                  | `config/nav-mobile.json`, `config/nav-integrations.json`, or `config/nav-releases.json` directly                                                                              |
| Edit Guides, CRM Platform, Onsite, Developer guide's API, CRMScript Reference, or Contribute content | `config/nav-learn.json`, `config/nav-online.json`, `config/nav-onsite.json`, `config/nav-api.json`, `config/nav-crmscript-ref.json`, or `config/nav-contribute.json` directly |
| Regenerate the database-tables reference                                                             | whatever produces `config/nav-database-tables.json`'s `pages` array (DB schema pipeline)                                                                                      |
| Regenerate the archive-provider or MDO-provider reference                                            | whatever produces `config/nav-archive-providers.json` / `config/nav-mdo-providers.json`'s `pages` arrays                                                                      |
| Edit the footer's links or socials                                                                   | `docs.json` directly, then re-run `tools/generate-footer.ps1` - see [Footer](#footer) below                                                                                   |
| Anything else in `docs.json` (theme, fonts, navbar)                                                  | `docs.json` directly - only `navigation` and `redirects` are split out                                                                                                        |

## Footer

`docs.json`'s `footer.links` and `footer.socials` drive Mintlify's native footer, rendered automatically on every normal content page.

Pages set to `mode: "custom"` opt out of Mintlify's built-in chrome entirely - no sidebar, no navbar, no footer - so they can control their own full-page layout. This repo uses that mode for most top-level category landing pages (`en/online/index.mdx`, `en/database/index.mdx`, and their language/section equivalents). 15 of those pages import `components/custom-mode-footer.mdx` directly to still show a matching footer.

<Note>
  `components/custom-mode-footer.mdx` is generated, not hand-written - its own header comment says so. It's produced by `tools/generate-footer.ps1` from `docs.json`'s `footer` section, not maintained independently.
</Note>

**Whenever `docs.json`'s `footer.links` or `footer.socials` changes, re-run the generator:**

```powershell theme={null}
.\tools\generate-footer.ps1
```

Skipping this step is how the native and custom-mode footers end up visually different from each other - icon order and wording can silently drift out of sync otherwise.

<Note>
  The script needs a UTF-8-BOM'd `.ps1` file to correctly parse its own non-ASCII characters (em-dashes) under Windows PowerShell 5.1. If you're on Windows without `pwsh` installed and see mojibake in the regenerated output, that's this, not a `docs.json` problem - the BOM requirement doesn't conflict with this repo's usual no-BOM policy, since that policy only covers content Mintlify actually parses (`.json`/`.md`/`.mdx`), not developer tooling scripts.
</Note>

## Editing redirects

`config/redirects.json` holds the array. `docs.json` only points at it. See [Redirects and redirect\_from][2] for the full guide - `redirect_from` frontmatter, wildcards, and the maintenance scripts (`tools/sort-redirects.py`, `tools/compact-redirects.py`) all work the same way, just against `config/redirects.json` instead of `docs.json`.

## Error pages

`docs.json`'s `errors.404` key controls the page Mintlify serves for any unmatched URL:

```json theme={null}
"errors": {
  "404": {
    "redirect": false,
    "description": "..."
  }
}
```

* `redirect` defaults to `true` - Mintlify sends every unmatched URL straight to the homepage. Set to `false` to show an actual 404 page instead; this site's previous DocFx-based 404 page never redirected, so this setting keeps that behavior.

* `title` and `description` can replace Mintlify's default heading and copy, but this site only sets `description` - Mintlify already renders its own large "404" numeral above the heading, so a custom `title` of `"404!"` just repeated it. Leaving `title` unset keeps Mintlify's own default heading next to that numeral.

* `description` supports MDX, including components - this site uses it to show a Hugo mascot illustration through an `<img>` tag rather than plain `![]()` markdown, for the `style`/`noZoom` control that gives. There's no dedicated light/dark prop on `<img>`, so two separate tags cover that: `images/404-hugo-board.png` (see [Files and folders][4]) with `className="block dark:hidden"` for light mode, and `images/404-hugo-sad.png` with `className="hidden dark:block"` for dark mode.

There is no dedicated `.mdx` file or custom-HTML override for this page - `errors.404` is the entire surface Mintlify exposes for it.

## Verify

After editing any split file, spot-check in `mint dev`: confirm the page you touched still appears in the right place in the nav, and that its sibling sections (the ones you didn't touch) are unaffected.

## Related content

* [Deployment and CI/CD][3] - how this site connects to GitHub and gets deployed, a separate concern from editing this config.
* [Files and folders][4] - where site-wide assets like `images/404-hugo.svg` live.

[1]: https://www.mintlify.com/docs/organize/settings#split-configuration-with-$ref

[2]: ./redirects

[3]: ./deployment

[4]: ./files-and-folders