mintlify · ethanpalm · Aug 5, 2025 · Jul 30, 2025 · Jul 30, 2025 · Jul 30, 2025
diff --git a/ai/contextual-menu.mdx b/ai/contextual-menu.mdx
@@ -5,6 +5,7 @@
 ---
 
 import { PreviewButton } from "/snippets/previewbutton.jsx"
+import IconsRequired from "/snippets/icons-required.mdx";
 
 The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users select the contextual menu on any page, they can copy content as context for AI tools or open conversations in ChatGPT, Claude, Perplexity, or a custom tool of your choice with your documentation already loaded as context.
 
@@ -34,8 +35,8 @@
   "options": [
     "copy",
     "view",
     "chatgpt",
     "claude",
     "perplexity"
   ]
 }
@@ -54,9 +55,7 @@
   The description of the option. Displayed beneath the title when the contextual menu is expanded.
 </ResponseField>
 
-<ResponseField name="icon" type="string" required>
-  The icon of the option. Accepts any icon from the [Icons](/components/icons) collection.
-</ResponseField>
+<IconsRequired />
 
 <ResponseField name="href" type="string | object" required>
   The href of the option. Use a string for simple links or an object for dynamic links with query parameters.

diff --git a/code.mdx b/code.mdx
@@ -57,7 +57,7 @@

 Enable syntax highlighting by specifying the programming language after the opening backticks of a code block.

 We use [Shiki](https://shiki.style/) for syntax highlighting and support all available languages. See the full list of [languages](https://shiki.style/languages) in Shiki's documentation.

 ```java
 class HelloWorld {
@@ -93,7 +93,7 @@
 
 ### Icon
 
-Add an icon to your code block. You can use [FontAwesome](https://fontawesome.com/icons) icons, [Lucide](https://lucide.dev/icons/) icons, or absolute URLs.
+Add an icon to your code block using the `icon` property. See [Icons](/components/icons) for all available options.
 
 ```javascript icon="square-js"
 const hello = "world";

diff --git a/components/accordions.mdx b/components/accordions.mdx
@@ -4,6 +4,8 @@ description: "Collapsible components to show and hide content"
 icon: "chevron-down"
 ---
 
+import IconsOptional from "/snippets/icons-optional.mdx";
+
 Accordions allow users to expand and collapse content sections. Use accordions for progressive disclosure and to organize information.
 
 ## Single accordion
@@ -97,11 +99,4 @@ Group related accordions together using `<AccordionGroup>`. This creates a cohes
   Whether the Accordion is open by default.
 </ResponseField>
 
-<ResponseField name="icon" type="string or svg">
-  A [Font Awesome icon](https://fontawesome.com/icons), [Lucide
-  icon](https://lucide.dev/icons), or SVG code.
-</ResponseField>
-
-<ResponseField name="iconType" type="string">
-  For Font Awesome icons, one of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or "brands".
-</ResponseField>
+<IconsOptional />
diff --git a/components/cards.mdx b/components/cards.mdx
@@ -4,6 +4,8 @@
 icon: "square-mouse-pointer"
 ---
 
+import IconsOptional from "/snippets/icons-optional.mdx";
+
 Use cards to create visual containers for content. Cards are flexible containers that can include text, icons, images, and links.
 
 ## Basic card
@@ -52,7 +54,7 @@
 </Card>
 ```

 ### Link cards with custom CTAs

 You can customize the call-to-action text and control whether an arrow appears. By default, arrows only show for external links.

@@ -102,19 +104,7 @@
   The title displayed on the card
 </ResponseField>
 
-<ResponseField name="icon" type="string or svg">
-  Icon to display on the card. Use a [Font Awesome icon](https://fontawesome.com/icons) name, [Lucide icon](https://lucide.dev/icons) name, or JSX-compatible SVG code wrapped in `icon={}`.
-
-  For custom SVG icons:
-  1. Use the [SVGR converter](https://react-svgr.com/playground/).
-  2. Copy the code inside the `<svg/>` tag.
-  3. Paste the code into your card.
-  4. Adjust height and width as needed.
-</ResponseField>
-
-<ResponseField name="iconType" type="string">
-  Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, or `brands`.
-</ResponseField>
+<IconsOptional />
 
 <ResponseField name="color" type="string">
   Icon color as a hex code (e.g., `#FF6B6B`).

diff --git a/components/icons.mdx b/components/icons.mdx
@@ -4,7 +4,9 @@
 icon: "flag"
 ---
 
-Use icons from Font Awesome, Lucide, URLs, or files in your project to enhance your documentation.
+import IconsRequired from "/snippets/icons-required.mdx";
+
+Use icons from Font Awesome, Lucide, SVGs, external URLs, or files in your project to enhance your documentation.
 
 <Icon icon="flag" size={32} />
 
@@ -24,13 +26,7 @@
 
 ## Properties
 
-<ResponseField name="icon" type="string" required>
-  A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon.
-</ResponseField>
-
-<ResponseField name="iconType" type="string">
-  For [Font Awesome](https://fontawesome.com/icons) icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
-</ResponseField>
+<IconsRequired />
 
 <ResponseField name="color" type="string">
   The color of the icon as a hex code (for example, `#FF5733`).

diff --git a/components/steps.mdx b/components/steps.mdx
@@ -4,6 +4,8 @@ description: "Sequence content using the Steps component"
 icon: "list-todo"
 ---
 
+import IconsOptional from "/snippets/icons-optional.mdx";
+
 Use steps to display a series of sequential actions or events. You can add as many steps as needed.
 
 <Steps>
@@ -48,13 +50,7 @@ Use steps to display a series of sequential actions or events. You can add as ma
   The content of a step either as plain text or components.
 </ResponseField>
 
-<ResponseField name="icon" type="string or svg">
-  A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}`.
-</ResponseField>
-
-<ResponseField name="iconType" type="string">
-  For Font Awesome icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
-</ResponseField>
+<IconsOptional />
 
 <ResponseField name="title" type="string">
   The title is the primary text for the step and shows up next to the indicator.

diff --git a/pages.mdx b/pages.mdx
@@ -4,6 +4,8 @@
 icon: "letter-text"
 ---
 
+import IconsOptional from "/snippets/icons-optional.mdx";
+
 Each page is an MDX file, which combines Markdown content with React components to let you create rich, interactive documentation.
 
 ## Page metadata
@@ -22,10 +24,7 @@
   A short title that displays in the sidebar navigation.
 </ResponseField>
 
-<ResponseField name="icon" type="string">
-  An icon next to your page title in the sidebar. Choose an icon from Font Awesome, Lucide, or use a custom URL. Configure your preferred icon library with the [icons library setting](/settings#param-icons).
-
-</ResponseField>
+<IconsOptional />
 
 <ResponseField name="tag" type="string">
   A tag that appears next to your page title in the sidebar.
@@ -68,7 +67,7 @@

 ### Custom

 Custom mode provides a minimalist layout that removes all elements except for the top navbar. Custom mode is a blank canvas to create landing pages or any other unique layouts that you want to have minimal navigation elements for.

 ```yaml
 ---
@@ -129,7 +128,7 @@

 ## Internal search keywords

 Enhance a specific page's discoverability in the built-in search by providing `keywords` in your metadata. These keywords won't appear as part of the page content or in search results, but users that search for them will be shown the page as a result.

 ```yaml
 ---

diff --git a/settings.mdx b/settings.mdx
@@ -5,6 +5,8 @@
 keywords: ["docs.json", "settings", "customization", "configuration"]
 ---
 
+import IconsOptional from "/snippets/icons-optional.mdx";
+
 The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more.
 
 Settings in `docs.json` apply globally to all pages.
@@ -13,7 +15,7 @@

 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.

 For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors:

 ```json
 {
@@ -146,7 +148,7 @@
       Icon library to use throughout your documentation. Defaults to `fontawesome`.
 
     <Note>
-      You can specify a URL for any individual icon, regardless of the library setting.
+      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.
     </Note>
     </ResponseField>
 
@@ -158,7 +160,7 @@

  <Expandable title="Fonts">
    <ResponseField name="family" type="string" required>
      Font family, such as "Open Sans", "Playfair Display."
    </ResponseField>
    <ResponseField name="weight" type="number">
      Font weight, such as 400 or 700. Variable fonts support precise weights  such as 550.
@@ -263,12 +265,12 @@

 ### Structure

 <ResponseField name="navbar" type="object">
  Navigation bar items.

  <Expandable title="Navbar">
    <ResponseField name="links" type="array of object">
      Links to display in the navbar

      <Expandable title="Links">
        <ResponseField name="label" type="string" required>
@@ -277,9 +279,7 @@
         <ResponseField name="href" type="string (uri)" required>
           URL or path for the link destination.
         </ResponseField>
-        <ResponseField name="icon" type="string | object">
-          Icon for the link. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.
-        </ResponseField>
+        <IconsOptional />
       </Expandable>
     </ResponseField>
     <ResponseField name="primary" type="object">
@@ -306,7 +306,7 @@

  <Expandable title="Navigation">
    <ResponseField name="global" type="object">
      Global navigation elements that appear accross all pages and sections.

      <Expandable title="Global">
        <ResponseField name="languages" type="array of object">
@@ -356,9 +356,7 @@
 
               Minimum length: 1
             </ResponseField>
-            <ResponseField name="icon" type="string or object">
-              Icon for the tab. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.
-            </ResponseField>
+            <IconsOptional />
             <ResponseField name="hidden" type="boolean">
               Whether to hide this tab by default.
             </ResponseField>
@@ -376,9 +374,7 @@
 
               Minimum length: 1
             </ResponseField>
-            <ResponseField name="icon" type="string or object">
-              Icon for the anchor. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.
-            </ResponseField>
+            <IconsOptional />
             <ResponseField name="color" type="object">
               Custom colors for the anchor.
 
@@ -413,9 +409,7 @@
 
               Minimum length: 1
             </ResponseField>
-            <ResponseField name="icon" type="string or object">
-              Icon for the dropdown. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.
-            </ResponseField>
+            <IconsOptional />
             <ResponseField name="hidden" type="boolean">
               Whether to hide this dropdown by default.
             </ResponseField>
@@ -540,7 +534,7 @@
  Contextual menu for AI-optimized content and integrations.

  <Expandable title="Contextual">
    <ResponseField name="options" type="array of &quot;copy&quot; | &quot;view&quot; | &quot;chatgpt&quot; | &quot;claude&quot;" required>
      Actions available in the contextual menu. The first option appears as the default.
      - `copy`: Copy the current page as Markdown to the clipboard.
      - `view`: View the current page as Markdown in a new tab.
@@ -559,7 +553,7 @@

 ### API Configurations

 <ResponseField name="api" type="object">
  API documentation and interactive playground settings.

  <Expandable title="Api">
@@ -978,7 +972,7 @@
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
@@ -1021,7 +1015,7 @@
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
@@ -1030,8 +1024,8 @@
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
@@ -1152,7 +1146,7 @@
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
@@ -1195,7 +1189,7 @@
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
@@ -1204,8 +1198,8 @@
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
@@ -1290,10 +1284,10 @@
              {
                "dropdown": "Documentación",
                "icon": "book",
                "description": "Cómo usar el producto de Example Co.",
                "pages": [
                  {
                    "group": "Comenzando",
                    "pages": ["es/index", "es/quickstart"]
                  },
                  {
@@ -1313,7 +1307,7 @@
              {
                "dropdown": "Changelog",
                "icon": "history",
                "description": "Actualizaciones y cambios",
                "pages": ["es/changelog"]
              }
            ]
@@ -1341,7 +1335,7 @@
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
@@ -1384,7 +1378,7 @@
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
@@ -1393,8 +1387,8 @@
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {

diff --git a/snippets/icons-optional.mdx b/snippets/icons-optional.mdx
@@ -0,0 +1,23 @@
+<ResponseField name="icon" type="string">
+  The icon to display.
+
+  Options:
+  - [Font Awesome icon](https://fontawesome.com/icons) name
+  - [Lucide icon](https://lucide.dev/icons) name
+  - JSX-compatible SVG code wrapped in curly braces
+  - URL to an externally hosted icon
+  - Path to an icon file in your project
+
+  For custom SVG icons:
+  1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
+  1. Paste your SVG code into the SVG input field.
+  2. Copy the complete `<svg>...</svg>` element from the JSX output field.
+  3. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
+  4. Adjust `height` and `width` as needed.
+</ResponseField>
+
+<ResponseField name="iconType" type="string">
+  The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons. 
+
+  Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
+</ResponseField>
diff --git a/snippets/icons-required.mdx b/snippets/icons-required.mdx
@@ -0,0 +1,23 @@
+<ResponseField name="icon" type="string" required>
+  The icon to display.
+
+  Options:
+  - [Font Awesome icon](https://fontawesome.com/icons) name
+  - [Lucide icon](https://lucide.dev/icons) name
+  - JSX-compatible SVG code wrapped in curly braces
+  - URL to an externally hosted icon
+  - Path to an icon file in your project
+
+  For custom SVG icons:
+  1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
+  1. Paste your SVG code into the SVG input field.
+  2. Copy the complete `<svg>...</svg>` element from the JSX output field.
+  3. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
+  4. Adjust `height` and `width` as needed.
+</ResponseField>
+
+<ResponseField name="iconType" type="string">
+  The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons. 
+
+  Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
+</ResponseField>