docs: document custom icon functionality for docs.yml and navigation (#1703)

devin-ai-integration[bot] · chdeskur · devalog · web-flow · commit b57fe8e6189d · 2025-11-03T11:46:39.000-05:00
Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
Co-authored-by: Catherine Deskur &lt;catherine@buildwithfern.com&gt;
Co-authored-by: Devin Logan &lt;devinannlogan@gmail.com&gt;
diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml
@@ -114,3 +114,4 @@ exceptions:
   - RBAC
   - YAML
   - fern.config.json
+  - Font Awesome
diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
@@ -236,10 +236,12 @@ navbar-links:
   - type: minimal
     text: Contact support
     href: https://example.com/support
+    icon: fa-solid fa-headset
   - type: filled
     text: Login
     href: https://example.com/login
     rounded: false
+    icon: ./assets/icons/login-icon.svg
   - type: github
     value: https://github.com/example-company/fern
   - type: dropdown
@@ -278,11 +280,15 @@ navbar-links:
 </ParamField>
 
 <ParamField path="icon" type="string" required={false} toc={true}>
-  The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **left** of the text content. Pro and Brand Icons from Font Awesome are supported.
+  The icon to be used in the button. This icon will appear to the **left** of the text content.
+  
+  <Markdown src="/snippets/icons.mdx" />
 </ParamField>
 
 <ParamField path="rightIcon" type="string" required={false} toc={true}>
-  The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **right** of the text content. Pro and Brand Icons from Font Awesome are supported.
+  The icon to be used in the button. This icon will appear to the **right** of the text content.
+
+  <Markdown src="/snippets/icons.mdx" />
 
   By default, the `rightIcon` for a `filled` button is set to `arrow-right`.
 </ParamField>
diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx
@@ -199,17 +199,22 @@ navigation:
 
 ## Sidebar icons
 
-For icons to appear next to sections and pages, add the `icon` key. The value should be a valid [Font Awesome icon](https://fontawesome.com/icons) name. Pro and Brand Icons from Font Awesome are supported.
+Add icons next to sections and pages using the `icon` key.
+
+<Markdown src="/snippets/icons.mdx" />
 
 {/* <!-- vale off --> */}
-```yaml Example navigation config with icons
+```yaml Example config with different icon files {3, 6, 9}
 navigation:
   - section: Home
-    icon: fa-regular fa-home
+    icon: fa-regular fa-home  # Font Awesome icon
     contents:
-      - page: My page
-        icon: fa-regular fa-file
-        path: ./pages/my-page.mdx
+      - page: Introduction
+        icon: ./assets/icons/intro-icon.svg  # Custom image file
+        path: ./pages/intro.mdx
+      - page: Custom Features
+        icon: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z'/></svg>"  # Inline SVG
+        path: ./pages/custom.mdx
   - api: API Reference
     icon: fa-regular fa-puzzle
 ```
@@ -237,7 +242,9 @@ navigation:
 
 ## Tabs
 
-Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons are supported.
+Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. 
+
+<Markdown src="/snippets/icons.mdx" />
 
 <CodeBlock title="docs.yml">
 {/* <!-- vale off --> */}
@@ -246,13 +253,13 @@ Within the navigation, you can add `tabs`. Tabs are used to group sections toget
 tabs: 
   api: 
     display-name: API Reference
-    icon: puzzle
+    icon: puzzle # Font Awesome icon
   help:
     display-name: Help center
-    icon: home
+    icon: ./assets/icons/help-icon.svg  # Custom image file
   github:
     display-name: GitHub
-    icon: brands github
+    icon: brands github # Font Awesome icon
     href: https://github.com/fern-api/fern
     
  navigation: 
diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx
@@ -57,6 +57,7 @@ navigation:
 ```
 </CodeBlock>
 <CodeBlock title="products/product-b.yml">
+
 ```yaml
 tabs: 
   api: 
@@ -90,28 +91,33 @@ tabs:
 
 To define a product, add an item to the `products` list in `docs.yml`, specifying the `display-name` and `path`.
 
-The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`.
-
-<Note>If you provide both an `image` and an `icon`, the `image` will take precedence.</Note>
-
-The below example is a `docs.yml` configuration for a site with two products, Product A and Product B.
-
-<CodeBlock title="docs.yml">
-```yaml {2-3, 8-9}
-products:
-  - display-name: Product A
-    path: ./products/product-a.yml
-    icon: fa-solid fa-leaf # optional
-    slug: product-a # optional
-    subtitle: Product A subtitle # optional
-
-  - display-name: Product B
-    path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
-    image: ./images/product-b.png # optional
-    slug: product-b # optional
-    subtitle: Product B subtitle # optional
-```
-</CodeBlock>
+The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`. If you provide both an `image` and an `icon`, the `image` will take precedence.
+
+<Note title="Product icons">
+
+  <Markdown src="/snippets/icons.mdx" />
+
+  <CodeBlock title="docs.yml">
+  ```yaml maxLines=5
+  products:
+    - display-name: Product A
+      path: ./products/product-a.yml
+      icon: fa-solid fa-leaf  # Font Awesome icon
+      slug: product-a
+      subtitle: Product A subtitle
+    - display-name: Product B
+      path: ./products/product-b.yml
+      icon: ./assets/icons/product-b-icon.svg  # Custom image file
+      slug: product-b
+      subtitle: Product B subtitle
+    - display-name: Product C
+      path: ./products/product-c.yml
+      icon: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z'/></svg>"  # Inline SVG
+      slug: product-c
+      subtitle: Product C subtitle
+  ```
+  </CodeBlock>
+</Note>
 </Step>
 <Step title="Remove extra navigation from docs.yml">
 
@@ -324,4 +330,4 @@ The dropdown menus for product and version selectors can be customized using the
       <img src="webflow-version-selector.avif" alt="Example of a styled version selector" />
     </Frame>
   </Tab>
-</Tabs> 
+</Tabs>      
diff --git a/fern/snippets/icons.mdx b/fern/snippets/icons.mdx
@@ -0,0 +1,4 @@
+Icons support three formats:
+  - **Font Awesome icons**: Use icon names like `fa-solid fa-rocket`. Pro and Brand Icons from Font Awesome are supported.
+  - **Custom image files**: Use relative paths to image files (e.g., `./assets/icons/my-icon.svg` or `../assets/icons/my-icon.png`). Paths are relative to the `docs.yml` file.
+  - **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).
