Skip to main content
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. This page covers how that split works and where to make a given change. For redirect-specific guidance, see Redirects and redirect_from.

​
What lives where

​
How $ref resolves

Any key’s value can be replaced with an object holding a $ref:
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.
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.

​
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: 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.
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.
Whenever docs.json’s footer.links or footer.socials changes, re-run the generator:
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.
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.

​
Editing redirects

config/redirects.json holds the array. docs.json only points at it. See Redirects and redirect_from 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:
  • 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) 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 - how this site connects to GitHub and gets deployed, a separate concern from editing this config.
  • Files and folders - where site-wide assets like images/404-hugo.svg live.