Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 107 additions & 57 deletions editor/configurations.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Configurations"
description: "Edit site branding, colors, appearance, and feature settings from the Configurations panel in the Mintlify web editor, with real-time team sync."
description: "Edit site branding, appearance, navigation, and feature settings from the Configurations panel in the Mintlify web editor, with real-time team sync."
keywords: ["editor", "configurations", "settings", "branding", "theme"]
boost: 3
---
Expand All @@ -20,93 +20,126 @@
/>
</Frame>

## Brand your site
The panel is organized into sections that map to the top-level properties in your [`docs.json`](/organize/settings). Use the table of contents on the right to jump between sections.

Check warning on line 23 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L23

In general, use active voice instead of passive voice ('is organized').

## General

Set your site's identity and how it appears to visitors.

- **Docs title**: The name of your site. Appears in browser tabs and search results.
- **Description**: Brief summary of your documentation. Used for SEO and site metadata.
- **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files.
- **Name**: The name of your project. Appears in browser tabs and search results.
- **Description**: Brief overview of your project. Used for SEO and AEO.

## Branding

Upload the marks that identify your site.

- **Logo**: Your brand logo. Upload PNG or JPG files. Set separate light and dark versions and an optional click-through URL. To use an SVG logo, add the file to your repository and reference its path in your [`docs.json`](/organize/settings-appearance#logos).
- **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files. Set separate light and dark versions if needed.

## Customize colors and appearance
## Styling

Control your site's visual identity and color scheme.

- **Theme**: Choose a [theme](/customize/themes) for your site's overall appearance.
- **Primary color**: The main accent color used throughout your site for links, buttons, and highlights.
- **Light mode color**: Accent color variation for light mode. How themes apply this varies by theme.
- **Dark mode color**: Accent color variation for dark mode. How themes apply this varies by theme.
- **Logo**: Your brand logo. Upload PNG or JPG files. You can set different logos for light and dark modes. To use an SVG logo, add the file to your repository via Git and reference its path in your [docs.json](/organize/settings-appearance#logos) configuration.
- **Logo link**: Where users go when they click your logo. Typically your homepage or marketing site.
- **Background colors**: Set custom background colors for light and dark modes separately.
- **Background image**: Add a background image to your site. Upload PNG, GIF, or JPG files.
- **Background decoration**: Apply visual styles to your background image.
- **Theme toggle**: Show or hide the light/dark mode switcher for users.
- **Default theme**: Set whether your site loads in light or dark mode by default.

## Set custom fonts
- **Light color**: Accent color used in dark mode. How themes apply this varies by theme.
- **Dark color**: Accent color used in light mode. How themes apply this varies by theme.
- **Background color**: Custom background colors for light and dark modes.
- **Icon library**: Icon library used for all icon properties. Defaults to `fontawesome`.
- **Strict appearance**: Lock the site to a single appearance mode and hide the theme toggle.
- **Default appearance**: Whether your site loads in `system`, `light`, or `dark` mode by default.
- **Background decoration**: Apply a visual style (`gradient`, `grid`, or `windows`) to your background.
- **Background image**: Optional background image. Set a single image or separate light and dark versions.

Replace default fonts with your brand's typography.
## Typography

- **Default font**: The base font family and weight for all text. Provide a source URL and format (WOFF or WOFF2).
- **Heading font**: Font family and weight specifically for headings (h1, h2, etc.). Set separately from body text.
- **Body font**: Font family and weight for body text and paragraphs.
Replace default fonts with your brand's typography.

For each font, specify the family name, weight, source URL (like Google Fonts), and format.
- **Font family**: Any [Google Fonts](https://fonts.google.com/) family works out of the box. For a self-hosted font, provide a source URL and format (`woff` or `woff2`).
- **Weight**: Typically `400` for regular and `700` for bold. Variable fonts support precise weights like `550`.
- **Heading font**: Optional override applied to all headings (`h1`–`h6`).

Check warning on line 60 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L60

Don't put a space before or after a dash.
- **Body font**: Optional override applied to body text and the rest of the page.

Check warning on line 61 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L61

Use 'REST' instead of 'rest'.

## Configure header and banner
## Navbar

Add navigation elements to the top of your site.

- **Navbar links**: Add navigation links in your header. Each link includes text and a URL.
- **Banner**: Add a banner displayed at the top of every page.
- **Primary button**: The main call-to-action in your header. Set the type, label, and destination URL.
- **Navbar links**: Additional navigation links in your header. Each link includes text and a URL.

## Configure footer
## Footer

Add links and social media handles to your site footer.

- **Social links**: Add your profiles on platforms like GitHub, X (Twitter), LinkedIn, Discord, YouTube, Slack, and more.
- **Footer columns**: Organize footer links into columns with custom headings and link groups.
- **Social links**: Profiles on platforms like GitHub, X, LinkedIn, Discord, YouTube, and Slack.
- **Footer columns**: Enable to organize footer links into up to four columns with custom headings.

## Banner

## Enhance content
Display an announcement bar across the top of every page.

- **Content**: The banner text. Supports basic MDX formatting like links, bold, and italic. Custom components are not supported.
- **Dismissible**: Show a dismiss button on the right side of the banner.

Check warning on line 82 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L82

Use 'dismissible' instead of 'Dismissible'.
- **Type**: Visual style. `info` uses the primary brand color, `warning` uses an amber background, and `critical` uses a red background. Defaults to `info`.
- **Color**: Override the banner background color with a custom hex color. Set separate light and dark values for theme-aware colors.

## Thumbnail

Customize page thumbnails and social previews.

- **Background**: Custom background image for thumbnails.
- **Appearance**: Render thumbnails in `light` or `dark` mode. When unset, thumbnails are auto-generated from your theme colors.
- **Font**: Custom font for text in thumbnails.

## Content

Customize how content appears on your site.

- **Thumbnail background**: Set a custom background image for page thumbnails and social previews.
- **Thumbnail appearance**: Control how thumbnails display.
- **Thumbnail font**: Set a custom font for text in thumbnails.
- **Page eyebrow**: Add small labels preceding page titles.
- **Code block theme**: Choose the syntax highlighting theme for code blocks.
- **LaTeX support**: Enable mathematical notation rendering with LaTeX.
- **Icon library**: Choose the icon library to use for your site.
- **Code block theme**: Match the docs light/dark mode with `system`, always use a dark theme with `dark`, or pick a custom [Shiki](https://shiki.style/) theme.
- **Custom code languages**: Register additional syntax highlighting languages.
- **Page eyebrow**: Show small labels preceding page titles. Choose `section` or `breadcrumbs`.
- **Timestamps**: Show the date the content was last modified on all pages.
- **LaTeX**: Load LaTeX (KaTeX) stylesheets for mathematical notation rendering.

## Set up AI chat and search
## Context menu

Customize the search experience.
Configure the quick actions surfaced in the page context menu.

- **Search placeholder**: The text that appears in the search box before users type. Default is `Search or ask`.
- **Options**: Multi-select dropdown of actions like `copy`, `view`, and opening the page in `chatgpt`, `claude`, `cursor`, and other AI assistants.
- **Display**: Where to display the options. `header` (default) shows them in the top-of-page context menu; `toc` shows them in the table of contents sidebar.

## Navigation

## Connect integrations
Tune navigation behavior across your site.

Connect third-party tools for analytics, support, and compliance.
- **Drilldown**: Auto-navigate to the first page when a user clicks a navigation group.

Check warning on line 115 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L115

Use 'drilldown' instead of 'Drilldown'.

## API specifications
## Search

Customize the search experience and feedback.

- **Search placeholder**: The text that appears in the search box before users type. Default is `Search or ask`.
- **Feedback**: Show thumbs-up and thumbs-down buttons or a "Suggest edits" link on every page.

## API reference

Document your API endpoints.

- **OpenAPI specs**: Upload an OpenAPI specification file to generate API reference pages.
- **AsyncAPI specs**: Upload an AsyncAPI specification file to generate API reference pages.
- **Playground display**: Choose to display the interactive API playground, simple API playground, or no API playground.
- **OpenAPI specs**: Add OpenAPI specification files to generate API reference pages.
- **AsyncAPI specs**: Add AsyncAPI specification files to generate API reference pages.
- **MDX server**: Custom MDX server endpoints for the API playground.
- **Playground display**: Show the interactive API playground, the simple API playground, or no API playground.
- **Proxy server**: Enable or disable the proxy server for API requests.
- **`mdx.schema`**: Whether to render the schema section on API reference pages.

## Manage redirects
## Redirects

Use the **Redirects** section to add, edit, search, and remove redirects without manually editing your `docs.json` file. Redirects send users from old URLs to new ones, which is useful when you rename pages or restructure your documentation. For more information about redirect behavior, see [Redirects](/create/redirects).
Use the **Redirects** section to add, edit, search, and remove redirects without manually editing your `docs.json` file. Redirects send users from old URLs to new ones, which is useful when you rename pages or restructure your documentation. For more information, see [Redirects](/create/redirects).

Each redirect has the following fields:

- **Source**: The path to redirect from, like `/old-path`. Supports wildcards.
- **Destination**: The path to redirect to, like `/new-path`.
- **Destination**: The path to redirect to, like `/new-path`. Supports wildcards.
- **Status**: The HTTP status code for the redirect.
- `308`: Permanent redirect. Use this for content that has moved permanently. This is the default status.
- `307`: Temporary redirect. Use this when the move is temporary.
Expand All @@ -125,17 +158,34 @@
</Frame>

To add a redirect:
1. Click **Add redirect**

1. Click **Add redirect**.
2. Enter the source and destination.
3. Click **Save**.

To edit or remove an existing redirect:
1. Hover over the redirect.
2. Click the pencil icon to edit or the trash icon to remove.
To edit or remove an existing redirect, hover over the row and use the inline edit icon or the **X** to remove it.

## SEO

Configure metatags and indexing for search engines.

- **Metatags**: Custom `<meta>` tags applied across your site. Add key-value pairs for tags like `og:image` or `twitter:card`.

Check warning on line 172 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L172

Use 'metatags?' instead of 'Metatags'.
- **Indexing**: Choose whether to index hidden pages.

## Analytics

Connect analytics platforms to track visitor behavior. Supported providers include Amplitude, Mixpanel, Heap, Google Analytics, Google Tag Manager, PostHog, Plausible, Fathom, Segment, Hightouch, Hotjar, LogRocket, Microsoft Clarity, Intercom, Clearbit, and more.

Each entry renders as an inline row. Use the **X** icon to remove an integration.

## 404 page

Customize the experience when a user lands on a missing page.

- **Redirect to home**: When on, missing pages redirect to your home page. When off, a 404 page is shown and you can customize the title and description below.

Check warning on line 185 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L185

In general, use active voice instead of passive voice ('is shown').
- **Title**: Heading shown on the 404 page.
- **Description**: Subheading shown on the 404 page.

## Additional page behaviors
## Variables

- **404 pages**: Customize 404 pages and set up redirect behavior.
- **Menu drilldown**: Enable or disable auto-navigating to the first page when a user clicks a navigation group.
- **Timestamps**: Show "Last modified on [date]" on all pages.
- **SEO indexing**: Choose whether to index hidden pages for search engines.
Define custom variables that can be re-used throughout your content. Each variable is a key-value pair. Use the **X** icon to remove a variable.
Loading
Loading