restructure and condense

Author: devalog

fern/products/docs/pages/navigation/products.mdx

@@ -26,7 +26,7 @@ subtitle: Allow users to seamlessly navigate between different products you offe
 
 Each product can contain its own distinct versions, tabs, sections, pages, and API references. Products can share content as well. 
 
-Products can be either internal (with their own navigation structure hosted on your docs site) or external (linking to an external URL like a separate application or third-party documentation).
+Products can be internal (hosted on your site) or external (linking to external URLs).
 
 ## Add products to your docs
 
@@ -36,6 +36,10 @@ Products can be either internal (with their own navigation structure hosted on y
 Create a `products` folder inside of your `fern` folder. To specify a product's contents and navigational structure, add a `.yml` file to the `products` folder for each product.
 Make sure to include the `navigation` and `tabs` properties, if applicable.
 
+<Info title="External products">
+You can also define external products, which link to external URLs (separate applications, third-party documentation, or other external resources) instead of documentation within your site. They appear in the product switcher but navigate users to the specified URL when selected. Define external products directly in `docs.yml` (no product-specific `.yml` file is needed).
+</Info>
+
 ```bash {4, 7-8}
 fern/
   ├─ fern.config.json
@@ -45,6 +49,7 @@ fern/
     ├─ ...
     ├─ product-a.yml # Contents and navigation for Product A
     └─ product-b.yml # Contents and navigation for Product B
+    # No yml file needed for external products
 ```
 
 <CodeBlocks>
@@ -96,7 +101,7 @@ 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.
+The below example is a `docs.yml` configuration for a site with two internal products (Product A and Product B) and one external product (Product C).
 
 <CodeBlock title="docs.yml">
 ```yaml {2-3, 8-9}
@@ -112,56 +117,23 @@ products:
     image: ./images/product-b.png # optional
     slug: product-b # optional
     subtitle: Product B subtitle # optional
+  
+  - display-name: Product C 
+    href: https://dashboard.example.com # External product
+    icon: fa-solid fa-chart-line
+    subtitle: Product C subtitle
 ```
 </CodeBlock>
+<Note>
+External products (like Product C above) use `href` to link to external URLs and don't require a product-specific `.yml` file in the `products` folder. Optional parameters (`image`, `icon`, `subtitle`) are supported, but versions, tabs, and navigation are not.
+</Note>
 </Step>
 <Step title="Remove extra navigation from docs.yml">
 
 If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the product-specific `.yml` files. 
 </Step>
 </Steps>
 
-## Link to external products
-
-You can configure a product to link to an external URL instead of hosting documentation on your site. This is useful when you want to include links to separate applications, third-party documentation, or other external resources in your product switcher.
-
-External products appear in the product switcher alongside internal products but navigate users to the specified URL when selected.
-
-### Configure an external product
-
-To define an external product, add an item to the `products` list in `docs.yml` with an `href` instead of a `path`. You can still include optional parameters like `image`, `icon`, and `subtitle`.
-
-<CodeBlock title="docs.yml">
-```yaml
-products:
-  - display-name: API Documentation
-    path: ./products/api-docs.yml
-    icon: fa-solid fa-book
-    slug: api-docs
-    subtitle: Complete API reference
-
-  - display-name: Dashboard
-    href: https://dashboard.example.com
-    icon: fa-solid fa-chart-line
-    subtitle: Analytics and insights
-```
-</CodeBlock>
-
-In this example, "API Documentation" is an internal product with its own navigation structure, while "Dashboard" is an external product that links to `https://dashboard.example.com`.
-
-### External product properties
-
-External products support the following properties in `docs.yml`:
-
-- `display-name` (required) - The title displayed in the product switcher
-- `href` (required) - External URL to navigate to when the product is selected
-- `subtitle` (optional) - Brief description of the product
-- `icon` (optional) - Icon to display in the product switcher
-- `image` (optional) - Image to display in the product switcher (takes precedence over `icon`)
-- `audiences` (optional) - Control visibility across different documentation instances
-
-<Note>External products cannot have versions, tabs, or navigation structures since they link to external URLs.</Note>
-
 ### Add versioning to your products
 
 You can optionally add versions to your products. Versioned and unversioned products can live next to each other in your site.