🌿 Fern Scribe: - Add documentation on how to support versions wit...

fern/products/docs/pages/changelog/2025/6/5.mdx

@@ -0,0 +1,61 @@
+---
+title: Support versions with products
+description: Adding API versioning to products in your Fern documentation
+---
+
+# Versioning Your Products
+
+You can add version support to products in your documentation by configuring versions in your `docs.yml` file. Each product can have multiple versions, making it easy for users to navigate between different API versions.
+
+## Add Versions to Products
+
+Add a `versions` array to each product in your `docs.yml` file:
+
+```yaml
+products:
+  - display-name: Data API
+    path: ./products/data/versions/v2.yml
+    subtitle: Integrate with our data platform
+    icon: fa-light fa-database
+    image: ./assets/product-selector/data-api-image.svg
+    slug: data
+    versions:
+      - display-name: v2
+        slug: v2.0.0
+        path: ./products/data/versions/v2.yml
+      - display-name: v2 (beta)
+        slug: v2.0.0-beta
+        path: ./products/data/versions/v2-beta.yml
+      - display-name: v1 (legacy)
+        slug: v1.0.0
+        path: ./products/data/versions/v1.yml
+```
+
+Each version requires:
+- `display-name`: The name shown in the version selector
+- `slug`: A URL-friendly identifier for the version
+- `path`: Path to the version's documentation files
+
+## Version Organization
+
+Best practices for organizing versioned documentation:
+
+1. Create a `versions` directory for each product
+2. Store each version's documentation in a separate YAML file
+3. Name files consistently (e.g., `v1.yml`, `v2.yml`)
+4. Use clear version labels that indicate status (e.g., "beta", "legacy")
+
+## Example Structure
+
+```
+docs/
+├── products/
+│   └── data/
+│       └── versions/
+│           ├── v1.yml
+│           ├── v2.yml
+│           └── v2-beta.yml
+└── docs.yml
+```
+
+The version selector will automatically appear in your documentation when versions are configured, allowing users to easily switch between different API versions.

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

@@ -86,85 +86,75 @@ tabs:
 </Step>
 <Step title="Add your product configuration">
 
-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`. Each product requires:
 
-The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`.
+- `display-name` - The name shown in the product selector
+- `path` - Path to the product's YAML configuration file
 
-<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.
+Optional parameters:
+- `image` - Path to product icon image
+- `icon` - Font Awesome icon class (used if no image provided)
+- `subtitle` - Short description shown under product name
+- `slug` - URL-friendly identifier
+- `versions` - Configuration for product versions
 
 <CodeBlock title="docs.yml">
-```yaml {2-3, 8-9}
+```yaml
 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
+  - display-name: Data API
+    path: ./products/data/versions/v2.yml
+    subtitle: Integrate with Webflow
+    icon: fa-light fa-database
+    image: ./assets/product-selector/data-api-image.svg
+    slug: data
+    versions:
+      - display-name: v2
+        slug: v2.0.0
+        path: ./products/data/versions/v2.yml
+      - display-name: v2 (beta)
+        slug: v2.0.0-beta
+        path: ./products/data/versions/v2-beta.yml
+      - display-name: v1 (legacy)
+        slug: v1.0.0
+        path: ./products/data/versions/v1.yml
 ```
 </CodeBlock>
-</Step>
-<Step title="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.
+<Note>If you provide both an `image` and an `icon`, the `image` will take precedence.</Note>
 
-In the below example, Product A is **unversioned** and Product B is **versioned**:
+</Step>
+<Step title="Add versioning to your products (optional)">
 
-<CodeBlock>
+Products can be versioned or unversioned. For versioned products, organize version files in a subdirectory structure:
 
-  ```bash {8, 10-17}
-  fern/
-    ├─ fern.config.json
-    ├─ generators.yml
-    ├─ docs.yml
-    ├─ pages/
-      ├─ ...
-    └─ products/
-      ├── product-a.yml # basic unversioned product
-      └── product-b/ # versioned product
-          ├─ product-b.yml
+```bash
+fern/
+  └─ products/
+      └─ data-api/
+          ├─ data-api.yml     # Product config
           └─ versions/
-            ├─ latest/
-            │  ├─ latest.yml
-            │  └─ pages/...
-            └─ v2/
-              ├─ v2.yml
-              └─ pages/...
-  ```
-</CodeBlock>
+              ├─ v2/
+              │  ├─ v2.yml    # v2 config
+              │  └─ pages/    # v2 content
+              └─ v1/
+                 ├─ v1.yml    # v1 config
+                 └─ pages/    # v1 content
+```
 
-The top-level `doc.yml` configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this:
+Add version configuration in `docs.yml`:
 
-<CodeBlock title="docs.yml">
-```yaml {2, 8, 13-17}
+```yaml
 products:
-  - 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 # versioned
-    path: ./products/product-b/latest.yml # <-- default showing latest
-    image: ./images/product-b.png # optional
-    slug: product-b # optional
-    subtitle: Product B subtitle # optional
-    versions: # optional
-      - display-name: Latest
-        path: ./products/product-b/latest.yml
-      - display-name: V2
-        path: ./products/product-b/v2.yml
+  - display-name: Data API
+    path: ./products/data-api/versions/v2.yml  # Default version
+    versions:
+      - display-name: v2 
+        path: ./products/data-api/versions/v2.yml
+      - display-name: v1
+        path: ./products/data-api/versions/v1.yml
 ```
-</CodeBlock>
 
-For more information on setting up versioned products, follow our [versioning docs](/docs/navigation/versions).
+For more details on versioning, see our [versioning guide](/docs/navigation/versions).
 </Step>
 <Step title="Remove extra navigation from docs.yml">
 
@@ -234,4 +224,4 @@ The dropdown menus for product and version selectors can be customized using the
       <img src="webflow-version-selector.avif" alt="Example of a styled version selector" />
     </Frame>
   </Tab>
-</Tabs> 
+</Tabs>