From 92bd9ca210a1fe15bb458eb98e2497cbb9c80a89 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 29 Jul 2025 16:53:48 -0400 Subject: [PATCH] clarify how product and version switchers work together --- .../docs/pages/navigation/products.mdx | 63 ++++++++++++------- .../docs/pages/navigation/versions.mdx | 11 +++- 2 files changed, 51 insertions(+), 23 deletions(-) diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 675fb5f65..9b0da337e 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -32,15 +32,15 @@ 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. -```bash +```bash {4, 7-8} fern/ ├─ fern.config.json ├─ generators.yml - ├─ docs.yml + ├─ docs.yml # Site-level contents and navigation └─ products/ ├─ ... - ├─ product-a.yml - └─ product-b.yml + ├─ product-a.yml # Contents and navigation for Product A + └─ product-b.yml # Contents and navigation for Product B ``` @@ -92,10 +92,34 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions` If you provide both an `image` and an `icon`, the `image` will take precedence. - - Products can be versioned or unversioned. The following is an example of how more complex products might be organized: +The below example is a `docs.yml` configuration for a site with two products, Product A and Product B. - ```bash + +```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/latest.yml # <-- default showing latest + image: ./images/product-b.png # optional + slug: product-b # optional + subtitle: Product B subtitle # optional +``` + + +### Add versioning to your products (optional) + +You can optionally add versions to a product. Versioned and unversioned products can live next to each other in your site. Each version of a single product has its own `yml` file. + +In the below example, Product A is **unversioned** and Product B is **versioned**: + + + + ```bash {8, 10-17} fern/ ├─ fern.config.json ├─ generators.yml @@ -104,35 +128,30 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions` ├─ ... └─ products/ ├── product-a.yml # basic unversioned product - ├── product-b/ # unversioned product with product-specific pages - │ ├─ pages/... - │ └─ product-with-pages.yml - └── product-c/ # versioned product - ├─ product-c.yml + └── product-b/ # versioned product + ├─ product-b.yml └─ versions/ - ├─ v1/ - │ ├─ v1.yml + ├─ latest/ + │ ├─ latest.yml │ └─ pages/... └─ v2/ ├─ v2.yml └─ pages/... ``` + - For more information on setting up versions, follow our [versioning docs](/learn/docs/building-and-customizing-your-docs/versioning). - - - +The top-level `doc.yml` configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this: -```yaml +```yaml {2, 8, 13-17} products: - - display-name: Product A + - display-name: Product A # unversioned path: ./products/product-a.yml icon: fa-solid fa-leaf # optional slug: product-a # optional subtitle: Product A subtitle # optional - - display-name: Product B + - display-name: Product B # versioned path: ./products/product-b/latest.yml # <-- default showing latest image: ./images/product-b.png # optional slug: product-b # optional @@ -145,6 +164,8 @@ products: ``` +For more information on setting up versioned products, follow our [versioning docs](/docs/navigation/versions). + ### 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. diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 630a37998..4d8313492 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -14,9 +14,10 @@ Each version of your docs can contain its own distinct tabs, sections, pages, an ### Define your versions -Create a `versions` folder inside of your `fern` folder. TO specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. +Create a `versions` folder inside of your `fern` folder. To specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. -```bash + +```bash {7-11} fern/ ├─ fern.config.json ├─ generators.yml @@ -29,6 +30,10 @@ fern/ ├─ v2-2/pages/... └─ v2-2.yml ``` + + + +Version-specific `yml` files: @@ -73,6 +78,8 @@ tabs: +You can also have multiple products, some versioned and some unversioned. For more information on setting up multiple products, follow our [product switching docs](/docs/navigation/products). + ### Add your version configuration To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`.