From 900f64289579075dff91d9b5e0bd258348a12172 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 3 Nov 2025 14:57:08 +0000 Subject: [PATCH 1/4] Document external product links feature Add documentation for the new feature that allows products to link to external URLs using href instead of path. This enables users to include links to separate applications or third-party documentation in their product switcher. Changes: - Add new section 'Link to external products' with configuration examples - Document external product properties (href, display-name, subtitle, icon, image, audiences) - Add changelog entry for 2025-11-03 - Clarify that products can be internal or external Co-Authored-By: Catherine Deskur --- .../docs/pages/changelog/2025-11-03.mdx | 23 +++++++++ .../docs/pages/navigation/products.mdx | 47 ++++++++++++++++++- 2 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2025-11-03.mdx diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx new file mode 100644 index 000000000..3d7a93182 --- /dev/null +++ b/fern/products/docs/pages/changelog/2025-11-03.mdx @@ -0,0 +1,23 @@ +## External product links + +You can now configure products to link to external URLs 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. + +To define an external product, add an item to the `products` list in `docs.yml` with an `href` instead of a `path`: + +```yaml title="docs.yml" +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 +``` + +Visit the [product switching documentation](/learn/docs/navigation/products#link-to-external-products) to learn more. diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index f0879c16e..9cc31d703 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -26,6 +26,8 @@ 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). + ## Add products to your docs @@ -119,9 +121,50 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure +## 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`. + + +```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 +``` + + +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 + +External products cannot have versions, tabs, or navigation structures since they link to external URLs. + ### 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. +You can optionally add versions to your products. Versioned and unversioned products can live next to each other in your site. For standalone versioning without products, see our [Versioning guide](/docs/configuration/versions). @@ -324,4 +367,4 @@ The dropdown menus for product and version selectors can be customized using the Example of a styled version selector - \ No newline at end of file + \ No newline at end of file From 52af3a3e238fca6b8e3b1bf62d036e4ddaf914ec Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 3 Nov 2025 12:36:12 -0500 Subject: [PATCH 2/4] restructure and condense --- .../docs/pages/navigation/products.mdx | 58 +++++-------------- 1 file changed, 15 insertions(+), 43 deletions(-) diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 9cc31d703..2338dbafc 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/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. + +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). + + ```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 ``` @@ -96,7 +101,7 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions` If you provide both an `image` and an `icon`, the `image` will take precedence. -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). ```yaml {2-3, 8-9} @@ -112,8 +117,16 @@ 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 ``` + +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. + @@ -121,47 +134,6 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure -## 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`. - - -```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 -``` - - -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 - -External products cannot have versions, tabs, or navigation structures since they link to external URLs. - ### 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. From 6d052d0e18bca8440584635357e90f0bca5357d9 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 3 Nov 2025 12:40:43 -0500 Subject: [PATCH 3/4] update changelog entry --- fern/products/docs/pages/changelog/2025-11-03.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx index 3d7a93182..0794df7d6 100644 --- a/fern/products/docs/pages/changelog/2025-11-03.mdx +++ b/fern/products/docs/pages/changelog/2025-11-03.mdx @@ -1,8 +1,8 @@ ## External product links -You can now configure products to link to external URLs 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. +You can now configure products to link to external URLs (separate applications, third-party documentation, or other external resources) instead of documentation within your site. -External products appear in the product switcher alongside internal products but navigate users to the specified URL when selected. +External products appear in the product switcher alongside internal products but navigate users to the specified URL when selected. Unlike internal products, external products are defined directly in `docs.yml` using `href`—no standalone product `.yml` file is needed. To define an external product, add an item to the `products` list in `docs.yml` with an `href` instead of a `path`: @@ -14,10 +14,10 @@ products: slug: api-docs subtitle: Complete API reference - - display-name: Dashboard + - display-name: Dashboard # External product href: https://dashboard.example.com icon: fa-solid fa-chart-line subtitle: Analytics and insights ``` -Visit the [product switching documentation](/learn/docs/navigation/products#link-to-external-products) to learn more. +Visit the [product switching documentation](/learn/docs/configuration/products#define-your-products) to learn more. From 184e3d12fb7c5227408be652b3a3159d07877d16 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 3 Nov 2025 13:00:22 -0500 Subject: [PATCH 4/4] update --- .../docs/pages/navigation/products.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 1cacf27a7..1c9b1d600 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -49,7 +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 + # No separate yml file needed for external products ``` @@ -96,9 +96,9 @@ tabs: -To define a product, add an item to the `products` list in `docs.yml`, specifying the `display-name` and `path`. +To define a product, add an item to the `products` list in `docs.yml`, specifying the `display-name` and either `path` (for internal products) or `href` (for external products). -The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`. If you provide both an `image` and an `icon`, the `image` will take precedence. +For both internal and external products, `image`, `icon`, and `subtitle` are optional parameters. If you provide both an `image` and an `icon`, the `image` will take precedence. Internal products additionally support the optional `slug` and `versions` parameters. @@ -107,7 +107,7 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions` 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). -```yaml {2-3, 8-9} +```yaml {2-3, 8-9, 14-15} products: - display-name: Product A path: ./products/product-a.yml @@ -128,19 +128,21 @@ products: ``` -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. - - 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. + + + External products don't support `navigation` and `tabs` fields. + + ### 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. +You can optionally add versions to your internal products. Versioned and unversioned products can live next to each other in your site. Versions are not supported for external products. For standalone versioning without products, see our [Versioning guide](/docs/configuration/versions).