cut down content, move into snippet

devalog · devalog · commit 78cd80e12ec6 · 2025-11-03T11:42:28.000-05:00
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
@@ -267,19 +267,15 @@ navbar-links:
 </ParamField>
 
 <ParamField path="icon" type="string" required={false} toc={true}>
-  The icon to be used in the button. This icon will appear to the **left** of the text content. Supports three formats:
+  The icon to be used in the button. This icon will appear to the **left** of the text content.
   
-  - **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>"`).
+  <Markdown src="/snippets/icons.mdx" />
 </ParamField>
 
 <ParamField path="rightIcon" type="string" required={false} toc={true}>
-  The icon to be used in the button. This icon will appear to the **right** of the text content. Supports three formats:
-  
-  - **Font Awesome icons**: Use icon names like `fa-solid fa-arrow-right`. 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>"`).
+  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,62 +199,27 @@ navigation:
 
 ## Sidebar icons
 
-Add icons next to sections and pages using the `icon` key. Icons support three formats:
+Add icons next to sections and pages using the `icon` key.
 
-- **Font Awesome icons**: Use icon names like `fa-regular fa-home`. 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 YAML file where the icon is declared.
-- **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).
-
-### Font Awesome icons
+<Markdown src="/snippets/icons.mdx" />
 
 {/* <!-- vale off --> */}
-```yaml Example navigation config with Font Awesome 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
 ```
 {/* <!-- vale on --> */}
 
-### Custom image files
-
-To use custom image files as icons, upload your image files to your docs assets folder, then reference them using relative paths. Paths are resolved relative to the YAML file where the icon is declared.
-
-{/* <!-- vale off --> */}
-```yaml Example navigation config with custom image icons
-navigation:
-  - section: Products
-    icon: ./assets/icons/products-icon.svg
-    contents:
-      - page: Product A
-        icon: ./assets/icons/product-a.png
-        path: ./pages/product-a.mdx
-      - page: Product B
-        icon: ./assets/icons/product-b.png
-        path: ./pages/product-b.mdx
-```
-{/* <!-- vale on --> */}
-
-### Inline SVG icons
-
-You can also provide inline SVG strings directly in your configuration. Wrap the SVG in quotes to ensure proper YAML parsing.
-
-{/* <!-- vale off --> */}
-```yaml Example navigation config with inline SVG icons
-navigation:
-  - section: Custom Section
-    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>"
-    contents:
-      - page: Custom Page
-        path: ./pages/custom-page.mdx
-```
-{/* <!-- vale on --> */}
-
 ## Links
 
 You can add a link to an external page within your sidebar navigation with the following configuration:
@@ -277,11 +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`. Icons support three formats:
+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`. 
 
-- **Font Awesome icons**: Use icon names like `puzzle` or `fa-solid fa-puzzle`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons 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 YAML file where the icon is declared.
-- **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).
+<Markdown src="/snippets/icons.mdx" />
 
 <CodeBlock title="docs.yml">
 {/* <!-- vale off --> */}
@@ -290,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,65 +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>
-
-### Product icons
-
-Product icons support three formats:
-
-- **Font Awesome icons**: Use icon names like `fa-solid fa-leaf`. 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>"`).
-
-#### Font Awesome icons
-
-<CodeBlock title="docs.yml">
-```yaml
-products:
-  - display-name: Product A
-    path: ./products/product-a.yml
-    icon: fa-solid fa-leaf
-    slug: product-a
-    subtitle: Product A subtitle
-```
-</CodeBlock>
-
-#### Custom image files
-
-To use custom image files as product icons, upload your image files to your docs assets folder, then reference them using relative paths. Paths are resolved relative to the `docs.yml` file.
-
-<CodeBlock title="docs.yml">
-```yaml
-products:
-  - display-name: Product A
-    path: ./products/product-a.yml
-    icon: ./assets/icons/product-a-icon.svg
-    slug: product-a
-    subtitle: Product A subtitle
-  - display-name: Product B
-    path: ./products/product-b.yml
-    icon: ./assets/icons/product-b-icon.png
-    slug: product-b
-    subtitle: Product B subtitle
-```
-</CodeBlock>
-
-#### Inline SVG icons
-
-Wrap the SVG in quotes to ensure proper YAML parsing.
-
-<CodeBlock title="docs.yml">
-```yaml
-products:
-  - display-name: Product A
-    path: ./products/product-a.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>"
-    slug: product-a
-    subtitle: Product A subtitle
-```
-</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">
 
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>"`).
