Skip to content

Add fonts configuration documentation #1571

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

Merged
ethanpalm merged 5 commits into from
Oct 17, 2025
Merged

Add fonts configuration documentation #1571

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
62c233e
Update settings/fonts.mdx
mintlify[bot] Oct 16, 2025
06bc79a
Update docs.json
mintlify[bot] Oct 16, 2025
5877c82
update fonts info in docs.json
ethanpalm Oct 16, 2025
272d587
move fonts file
ethanpalm Oct 16, 2025
5750458
copy edit
ethanpalm Oct 16, 2025
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
149 changes: 149 additions & 0 deletions customize/fonts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
---
title: "Fonts"
description: "Configure custom fonts"
---

Set a custom font for your entire site or separately for headings and body text. Use Google Fonts, local font files, or externally hosted fonts. The default font varies by theme.

Fonts are controlled by the [fonts property](/organize/settings#param-fonts) in your `docs.json`.

Check warning on line 8 in customize/fonts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/fonts.mdx#L8 

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

## Google Fonts

Check warning on line 10 in customize/fonts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/fonts.mdx#L10 

'Google Fonts' should use sentence-style capitalization.

Mintlify automatically loads [Google Fonts](https://fonts.google.com) when you specify a font family name in your `docs.json`.

```json docs.json
"fonts": {
"family": "Inter"
}
```

## Local fonts

To use local fonts, place your font files in your project directory and reference them in your `docs.json` configuration.

### Setting up local fonts

<Steps>
<Step title="Add font files to your project">
For example, create a `fonts` directory and add your font files:

```text
your-project/
├── fonts/
│ ├── InterDisplay-Regular.woff2
│ └── InterDisplay-Bold.woff2
├── docs.json
└── ...
```
</Step>

<Step title="Configure fonts in docs.json">
Reference your local fonts using relative paths from your project root:

```json docs.json
{
"fonts": {
"family": "InterDisplay",
"source": "/fonts/InterDisplay-Regular.woff2",
"format": "woff2",
"weight": 400
}
}
```
</Step>
</Steps>

### Local fonts for headings and body

Configure separate local fonts for headings and body text in your `docs.json`:

```json docs.json
{
"fonts": {
"heading": {
"family": "InterDisplay",
"source": "/fonts/InterDisplay-Bold.woff2",
"format": "woff2",
"weight": 700
},
"body": {
"family": "InterDisplay",
"source": "/fonts/InterDisplay-Regular.woff2",
"format": "woff2",
"weight": 400
}
}
}
```

## Externally hosted fonts

Use externally hosted fonts by referencing a font source URL in your `docs.json`:

```json docs.json
{
"fonts": {
"family": "Hubot Sans",
"source": "https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2",
"format": "woff2",
"weight": 400
}
}
```

## Font configuration reference

<ResponseField name="fonts" type="object">
Font configuration for your documentation.

<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Font family name, such as "Inter" or "Playfair Display".
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file, such as `/assets/fonts/InterDisplay.woff2`. Google Fonts are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="'woff' | 'woff2'">
Font file format. Required when using the `source` field.
</ResponseField>
<ResponseField name="heading" type="object">
Override font settings specifically for headings.

<Expandable title="Heading">
<ResponseField name="family" type="string" required>
Font family name for headings.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight for headings.
</ResponseField>
<ResponseField name="source" type="string (uri)">
URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for headings. Google Fonts are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="'woff' | 'woff2'">
Font file format for headings. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="body" type="object">
Override font settings specifically for body text.

<Expandable title="Body">
<ResponseField name="family" type="string" required>
Font family name for body text.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight for body text.
</ResponseField>
<ResponseField name="source" type="string (uri)">
URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for body text. Google Fonts are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="'woff' | 'woff2'">
Font file format for body text. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
"pages": [
"customize/custom-domain",
"customize/themes",
"customize/fonts",
"customize/custom-scripts",
"customize/react-components",
{
Expand Down
61 changes: 56 additions & 5 deletions organize/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,20 +189,71 @@
</ResponseField>

<ResponseField name="fonts" type="object">
Font configuration for the headings in your documentation. The default font varies by theme.
Set custom fonts for your documentation. The default font varies by theme.

<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans."
Font family, such as "Open Sans." [Google Fonts](https://fonts.google.com) family names are supported.

Check warning on line 196 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L196 

In general, use active voice instead of passive voice ('are supported').
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
URL to your font source, such as https://mintlify-assets.b-cdn.net/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.
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"'>
Font file format.
Font file format. Required when using the `source` field.
</ResponseField>
<ResponseField name="heading" type="object">
Override font settings specifically for headings.

<Expandable title="Heading">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans", "Playfair Display." [Google Fonts](https://fonts.google.com) family names are supported.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
</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;">
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="body" type="object">
Override font settings specifically for body text.

<Expandable title="Body">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans", "Playfair Display." [Google Fonts](https://fonts.google.com) family names are supported.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
</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;">
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -461,7 +512,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 515 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L515 

In general, use active voice instead of passive voice ('is expanded').
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -539,7 +590,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 593 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L593 

Use parentheses judiciously.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -573,7 +624,7 @@
</Expandable>
</ResponseField>

### API Configurations

Check warning on line 627 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L627 

'API Configurations' should use sentence-style capitalization.

<ResponseField name="api" type="object">
API documentation and interactive playground settings.
Expand Down Expand Up @@ -671,10 +722,10 @@
</Expandable>
</ResponseField>

### SEO and search

Check warning on line 725 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L725 

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

Check warning on line 725 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L725 

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

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

Check warning on line 728 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L728 

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

<Expandable title="Seo">
<ResponseField name="metatags" type="object">
Expand Down