Skip to content

Mintlify Docs Edits #2627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mintlify wants to merge 1 commit into from
Closed

Mintlify Docs Edits #2627

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 24 additions & 16 deletions organize/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Global settings"
description: "Configure site-wide settings in docs.json."
keywords: ["docs.json", "settings", "customization", "configuration", "logo", "colors", "fonts", "background", "appearance", "last modified date", "timestamp"]
keywords: ["docs.json","settings","customization","configuration","logo","colors","fonts","background","appearance","last modified date","timestamp"]
---

import IconsOptional from "/snippets/icons-optional.mdx";
Expand All @@ -10,6 +10,8 @@

Settings in `docs.json` apply globally to all pages.

### daniel is cool

Check warning on line 13 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L13 

'daniel is cool' should use sentence-style capitalization.

Check warning on line 13 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L13 

Did you really mean 'daniel'?
Copy link

@cursor cursor bot Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Test content accidentally committed to documentation

High Severity

The line ### daniel is cool appears to be accidentally committed test or debug content. This personal note has no relevance to the "Global settings" documentation and would be visible to users in production. It's positioned between the introduction text and the "Setting up your docs.json" section where it clearly doesn't belong.

Fix in Cursor Fix in Web


## Setting up your `docs.json`

To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow.
Expand Down Expand Up @@ -50,7 +52,7 @@
</ResponseField>

<ResponseField name="colors" type="object" required>
The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements.

Check warning on line 55 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L55 

Avoid using 'will'.

<Expandable title="Colors">
<ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
Expand Down Expand Up @@ -115,7 +117,7 @@
Background image for your thumbnails. Can be a relative path or absolute URL.
</ResponseField>
<ResponseField name="fonts" type="object">
Font configuration for thumbnails. Only Google Fonts family names are supported.

Check warning on line 120 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L120 

In general, use active voice instead of passive voice ('are supported').

<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Expand All @@ -135,7 +137,7 @@
</ResponseField>
<ResponseField name="latex" type="boolean">
Controls whether LaTeX stylesheets are included, overriding automatic detection. By default, Mintlify automatically detects LaTeX usage in your content and loads the necessary stylesheets.

- Set to `true` to force-load LaTeX stylesheets when automatic detection fails to recognize your mathematical expressions.
- Set to `false` to prevent loading LaTeX stylesheets for improved performance if you don't use mathematical expressions but have content that triggers false-positive detection.
</ResponseField>
Expand Down Expand Up @@ -217,7 +219,7 @@
<ResponseField name="library" type='"fontawesome" | "lucide"' required>
Icon library to use throughout your documentation. Defaults to `fontawesome`.

You can only use one icon library for your project. All icon names in your documentation must come from the same library.
You can only use one icon library for your project. All icon names in your documentation must come from the same library.

<Note>
You can specify a URL to an externally hosted icon, path to an icon file in your project, or JSX-compatible SVG code for any individual icon, regardless of the library setting.
Expand All @@ -238,10 +240,10 @@
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:

- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type='"woff" | "woff2"'>
Expand All @@ -259,13 +261,13 @@
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:

- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="&quot;woff&quot; | &quot;woff2&quot;">
<ResponseField name="format" type='"woff" | "woff2"'>
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
Expand All @@ -282,13 +284,13 @@
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:

- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="&quot;woff&quot; | &quot;woff2&quot;">
<ResponseField name="format" type='"woff" | "woff2"'>
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
Expand Down Expand Up @@ -550,7 +552,7 @@

<Expandable title="Interaction">
<ResponseField name="drilldown" type="boolean">
Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.

Check warning on line 555 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L555 

In general, use active voice instead of passive voice ('is expanded').
</ResponseField>
</Expandable>
</ResponseField>
Expand All @@ -560,7 +562,7 @@

<Expandable title="Metadata">
<ResponseField name="timestamp" type="boolean">
Enable the last modified date on all pages. When enabled, all pages will display the date the content was last modified. Defaults to `false`.

Check warning on line 565 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L565 

Avoid using 'will'.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -613,7 +615,7 @@

<Expandable title="Banner">
<ResponseField name="content" type="string" required>
The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported. For example:

Check warning on line 618 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L618 

Use 'aren't' instead of 'are not'.

```json
{
Expand All @@ -638,7 +640,7 @@
Destination path to redirect to. Example: `/new-page`
</ResponseField>
<ResponseField name="permanent" type="boolean">
Whether to use a permanent redirect (301). Defaults to `true`.

Check warning on line 643 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L643 

Use parentheses judiciously.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -675,12 +677,12 @@
Link destination for the custom option. Can be a simple URL string or an object with `base` and optional `query` parameters.

Placeholder values:

- `$page`: Current page content
- `$path`: Current page path
- `$mcp`: MCP server URL
</ResponseField>
</Expandable>

<img
src="/images/page-context-menu.png"
alt="Contextual Menu"
Expand All @@ -694,7 +696,7 @@
</Expandable>
</ResponseField>

### API Configurations

Check warning on line 699 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L699 

'API Configurations' should use sentence-style capitalization.

<ResponseField name="api" type="object">
API documentation and interactive playground settings.
Expand All @@ -715,12 +717,13 @@
Do not include a leading slash.
</ResponseField>
</Expandable>

<CodeGroup>

```json Single file
"openapi": "openapi.json"
```


```json Multiple files
"openapi": [
"openapi/v1.json",
Expand All @@ -729,12 +732,14 @@
]
```


```json Directory
"openapi": {
"source": "openapi.json",
"directory": "api-docs"
}
```

</CodeGroup>
</ResponseField>
<ResponseField name="asyncapi" type="string or array or object">
Expand All @@ -752,12 +757,13 @@
Do not include a leading slash.
</ResponseField>
</Expandable>

<CodeGroup>

```json Single file
"asyncapi": "asyncapi.json"
```


```json Multiple files
"asyncapi": [
"asyncapi/events.yaml",
Expand All @@ -766,14 +772,15 @@
]
```


```json Directory
"asyncapi": {
"source": "asyncapi.json",
"directory": "websockets"
}
```
</CodeGroup>

</CodeGroup>
</ResponseField>
<ResponseField name="params" type="object">
Display settings for API parameters.
Expand Down Expand Up @@ -802,6 +809,7 @@
<Expandable title="Examples">
<ResponseField name="languages" type="array of string">
Example languages for the autogenerated API snippets. Supported languages include:

- `bash` (displayed as cURL)
- `go`
- `java`
Expand Down Expand Up @@ -847,10 +855,10 @@
</Expandable>
</ResponseField>

### SEO and search

Check warning on line 858 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L858 

'SEO and search' should use sentence-style capitalization.

Check warning on line 858 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L858 

Spell out 'SEO', if it's unfamiliar to the audience.

<ResponseField name="seo" type="object">
SEO indexing configurations.

Check warning on line 861 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L861 

Spell out 'SEO', if it's unfamiliar to the audience.

<Expandable title="Seo">
<ResponseField name="metatags" type="object">
Expand Down Expand Up @@ -1068,7 +1076,7 @@
<Expandable title="Telemetry">
<ResponseField name="enabled" type="boolean">
Whether to enable telemetry.

<Note>
When set to `false`, feedback features are also disabled and do not appear on your documentation pages.
</Note>
Expand Down