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..0794df7d6 --- /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 (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. 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`: + +```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 # External product + href: https://dashboard.example.com + icon: fa-solid fa-chart-line + subtitle: Analytics and insights +``` + +Visit the [product switching documentation](/learn/docs/configuration/products#define-your-products) to learn more. diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index f0f259f3a..1c9b1d600 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 internal (hosted on your site) or external (linking to external URLs). + ## Add products to your docs @@ -34,6 +36,10 @@ Each product can contain its own distinct versions, tabs, sections, pages, and A 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 @@ -43,6 +49,7 @@ fern/ ├─ ... ├─ product-a.yml # Contents and navigation for Product A └─ product-b.yml # Contents and navigation for Product B + # No separate yml file needed for external products ``` @@ -89,45 +96,53 @@ 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`. If you provide both an `image` and an `icon`, the `image` will take precedence. +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). +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. + - - - - ```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: "" # Inline SVG - slug: product-c - subtitle: Product C subtitle - ``` - + +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, 14-15} +products: + - display-name: Product A + path: ./products/product-a.yml + icon: fa-solid fa-leaf # Font Awesome icon + slug: product-a # optional + subtitle: Product A subtitle # optional + + - display-name: Product B + path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest + icon: ./assets/icons/product-b-icon.svg # Custom image file + slug: product-b # optional + subtitle: Product B subtitle # optional + + - display-name: Product C + href: https://dashboard.example.com # External product + icon: "" # Inline SVG + subtitle: Product C subtitle +``` + + 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). @@ -330,4 +345,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 +