diff --git a/customize/fonts.mdx b/customize/fonts.mdx
new file mode 100644
index 000000000..9c4462802
--- /dev/null
+++ b/customize/fonts.mdx
@@ -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`.
+
+## Google Fonts
+
+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
+
+
+
+For example, create a `fonts` directory and add your font files:
+
+```text
+your-project/
+├── fonts/
+│ ├── InterDisplay-Regular.woff2
+│ └── InterDisplay-Bold.woff2
+├── 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
+ }
+}
+```
+
+
+
+### 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
+
+
+ Font configuration for your documentation.
+
+
+
+ Font family name, such as "Inter" or "Playfair Display".
+
+
+ Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
+
+
+ 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.
+
+
+ Font file format. Required when using the `source` field.
+
+
+ Override font settings specifically for headings.
+
+
+
+ Font family name for headings.
+
+
+ Font weight for headings.
+
+
+ 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.
+
+
+ Font file format for headings. Required when using the `source` field.
+
+
+
+
+ Override font settings specifically for body text.
+
+
+
+ Font family name for body text.
+
+
+ Font weight for body text.
+
+
+ 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.
+
+
+ Font file format for body text. Required when using the `source` field.
+
+
+
+
+
diff --git a/docs.json b/docs.json
index 6155db84c..4fd21412b 100644
--- a/docs.json
+++ b/docs.json
@@ -49,6 +49,7 @@
"pages": [
"customize/custom-domain",
"customize/themes",
+ "customize/fonts",
"customize/custom-scripts",
"customize/react-components",
{
diff --git a/organize/settings.mdx b/organize/settings.mdx
index 1068005b9..065ab1f8b 100644
--- a/organize/settings.mdx
+++ b/organize/settings.mdx
@@ -189,20 +189,71 @@ This section contains the full reference for the `docs.json` file.
- 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.
- Font family, such as "Open Sans."
+ Font family, such as "Open Sans." [Google Fonts](https://fonts.google.com) family names are supported.
- 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.
- 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.
- Font file format.
+ Font file format. Required when using the `source` field.
+
+
+ Override font settings specifically for headings.
+
+
+
+ Font family, such as "Open Sans", "Playfair Display." [Google Fonts](https://fonts.google.com) family names are supported.
+
+
+ Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
+
+
+ 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.
+
+
+ Font file format. Required when using the `source` field.
+
+
+
+
+ Override font settings specifically for body text.
+
+
+
+ Font family, such as "Open Sans", "Playfair Display." [Google Fonts](https://fonts.google.com) family names are supported.
+
+
+ Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
+
+
+ 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.
+
+
+ Font file format. Required when using the `source` field.
+
+