Site-wide settings allow you to customize the appearance, navigation, and core features of your documentation. By modifying your central configuration file, you can align the documentation with your brand and enable powerful tools like AI assistants, SEO templates, and versioning.
Previewing changes locally
Before pushing global changes to your live site, we recommend previewing them on your local machine.
- 1
Install the CLI
Install the command-line interface globally using npm so you can run the local development server.
npm i -g mint - 2
Start the development server
Navigate to the root of your documentation folder (where your configuration JSON file is located) and start the server.
mint dev - 3
View your site
Open the provided localhost URL in your browser. The server will automatically reload when you save changes to your configuration file.
Keep your local server running in the background while you tweak your theme colors and navigation. Seeing the changes in real-time makes styling much easier!
Core configuration options
Your global settings are managed in a central JSON file (such as gitdocai.json or docs.json) located at the root of your repository. Below are the primary areas you can configure.
Theme and branding
Control the visual identity of your documentation, including colors, fonts, and logos across light and dark modes.
| Property | Description | Example Value |
|---|---|---|
theme.preset | The base layout and styling preset. | "pearl" |
theme.default | The default color mode for new visitors. | "dark" or "light" |
theme.dark.bg_color | Background color for dark mode. | "#0a0a0a" |
theme.light.accent_color | Primary brand color for links and buttons. | "#2563eb" |
font_family | The primary typeface used across the site. | "Inter" |
logo | Paths to your light and dark mode SVG logos. | {"light": "/logo/light.svg"} |
"theme": {
"preset": "pearl",
"default": "dark",
"font_family": "Inter",
"dark": {
"bg_color": "#171717",
"text_color": "#ededed",
"accent_color": "#3b82f6"
}
}Features and integrations
Enable or disable built-in features to enhance the reader experience.
| Feature | Configuration Key | Effect |
|---|---|---|
| AI Assistant | assistant.enabled | Toggles the floating AI chat assistant. |
| Knowledge Base | kb.enabled | Activates the Help Center search and hero section. |
| SEO | seo.title_template | Sets the global browser tab title format (e.g., `"%s |
| Versioning | version_selector_enabled | Shows a dropdown to switch between API/Doc versions (e.g., v1, v2). |
Navigation
The navigation block defines how users browse your content. You can organize pages into Tabs (top-level), Groups (sidebar sections), and Pages (individual documents). You can also add global anchor links or external buttons to your navbar.
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "Get Started",
"pages": ["index", "quickstart"]
}
]
}
]
}Publishing your changes
Once you are happy with your configuration, deploying is completely automated.
flowchart LR
A["Edit JSON Config"] --> B["Commit & Push"]
B --> C["GitHub App Trigger"]
C --> D["Auto-Deploy to Production"]To enable this workflow, install our GitHub App (available via your dashboard). Once installed, any changes pushed to your default branch will automatically propagate to your live documentation site.
Ensure your JSON syntax is valid before pushing. A missing comma or unclosed bracket in your configuration file can cause the deployment to fail.
Troubleshooting
Running into issues while configuring your site? Check these common solutions:
The local dev environment isn't running
If the mint dev command fails or throws errors, your local dependencies might be out of date or corrupted. Run mint install in your terminal to cleanly re-install the required packages, then try starting the server again.
My page loads as a 404 error
This usually happens if you run the development server in the wrong directory. Ensure you are executing mint dev in the exact folder that contains your configuration file (docs.json or gitdocai.json).