Consolidate product versioning documentation to reduce page switching (Docs)

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

@@ -1,5 +1,5 @@
 ---
-title: Product Switching
+title: Product switching
 subtitle: Allow users to seamlessly navigate between different products you offer. 
 ---
 
@@ -24,7 +24,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. 
 
-## Add Products to Your Docs
+## Add products to your docs
 
 <Steps toc={true}>
 <Step title="Define your products">
@@ -104,16 +104,24 @@ products:
     subtitle: Product A subtitle # optional
 
   - display-name: Product B
-    path: ./products/product-b/latest.yml # <-- default showing latest
+    path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
     image: ./images/product-b.png # optional
     slug: product-b # optional
     subtitle: Product B subtitle # optional
 ```
 </CodeBlock>
 </Step>
-<Step title="Add versioning to your products (optional)">
+<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>
+
+### Add versioning to your products (optional)
+
+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 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>For standalone versioning without products, see our [Versioning guide](/docs/configuration/versions).</Note>
 
 In the below example, Product A is **unversioned** and Product B is **versioned**:
 
@@ -140,41 +148,69 @@ In the below example, Product A is **unversioned** and Product B is **versioned*
   ```
 </CodeBlock>
 
+<Steps>
+<Step title="Define your versions">
+Create a `versions` folder inside of folder of the product you want to version. 
+
+Each version of a single product has its own `yml` file. 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.
+
+Version-specific `yml` files:
+
+<Markdown src="/snippets/version-specific-yml-files.mdx" />
+
+</Step>
+<Step title="Add your version configuration">
+
+Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. 
+
 The top-level `doc.yml` configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this:
 
 <CodeBlock title="docs.yml">
-```yaml {2, 8, 13-19}
+```yaml {2, 8, 12-16}
 products:
   - display-name: Product A # unversioned
-    path: ./products/product-a.yml
+    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
+    path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
     image: ./images/product-b.png # optional
     slug: product-b # optional
     subtitle: Product B subtitle # optional
-    versions: # optional
+    versions: 
       - display-name: Latest
-        path: ./products/product-b/latest.yml
-        availability: beta
+        path: ./products/product-b/versions/latest/latest.yml # relative path to the version file
       - display-name: V2
-        path: ./products/product-b/v2.yml
-        availability: ga
+        path: ./products/product-b/versions/v2/v2.yml # relative path to the version file
 ```
 </CodeBlock>
 
-For more information on setting up versioned products, follow our [versioning docs](/docs/configuration/versions).
 </Step>
-<Step title="Remove extra navigation from docs.yml">
+<Step title="Indicate availability">
 
-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. 
+<Markdown src="/snippets/version-availability.mdx" />
+
+<CodeBlock title="docs.yml">
+```yaml {4}
+versions: 
+  - display-name: Latest          
+    path: ./products/product-b/versions/latest/latest.yml 
+    availability: beta
+  - display-name: V2
+    path: ./products/product-b/versions/v2/v2.yml
+    availability: stable
+```
+</CodeBlock>
+</Step>
+<Step title="Remove extra navigation">
+
+If your product-specific `.yml` files for **versioned products** includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files. 
 </Step>
 </Steps>
 
-## Customizing Selector Styling
+
+## Customize selector styling
 
 You can directly customize the appearance of the product and version selectors by targeting their CSS classes:
 
@@ -185,13 +221,9 @@ You can directly customize the appearance of the product and version selectors b
   <img src="webflow-dropdown-selector.avif" alt="Example of a styled product selector" />
 </Frame>
 
-### Common Styling Adjustments
-
-**Adjusting positioning:**
-Use `transform: translateY(Npx)` to adjust the vertical positioning of the selectors. This ensures that the product and version selectors match the line height of your logo for better visual alignment.
+### Common styling adjustments
 
-**Enhancing visual prominence:**
-You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site's design aesthetic.
+<Markdown src="/snippets/common-selector-styling.mdx" />
 
 ```css
 .fern-product-selector {
@@ -207,7 +239,7 @@ You can modify the border radius and add borders to make the selectors more prom
 }
 ```
 
-## Customizing Dropdown Styling
+### Customize dropdown styling
 
 The dropdown menus for product and version selectors can be customized using these specific CSS classes:
 

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

@@ -9,7 +9,7 @@ subtitle: Allow users to navigate between different versions of your docs.
 
 Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well. 
 
-**To add versions to your docs:**
+## Add versions to your docs
 
 <Steps toc={true}>
 <Step title="Define your versions">
@@ -25,107 +25,76 @@ fern/
   ├─ pages/
     ├─ ...
   └─ versions/
-    ├─ v2-1/pages/...
-    ├─ v2-1.yml
-    ├─ v2-2/pages/...
-    └─ v2-2.yml
+    ├─ latest/pages/...
+    ├─ latest.yml
+    ├─ v2/pages/...
+    └─ v2.yml
 ```
 </CodeBlock>
 
-
 Version-specific `yml` files:
 
-<CodeBlocks>
-<CodeBlock title="versions/v2-1.yml">
-```yaml
-navigation: 
-  - section: Introduction
-    contents: 
-      - page: My Page
-        path: ./v2-1/pages/my-page.mdx  # relative path to the file
-      - page: Shared Resource
-        path: ../shared-pages/shared-resource.mdx
-  - api: API Reference
-```
-</CodeBlock>
-<CodeBlock title="versions/v2-2.yml">
-```yaml
-tabs: 
-  api: 
-    title: API Reference
-    icon: puzzle
-  help:
-    title: Help Center
-    icon: home
-
- navigation:
-  - tab: api
-     contents:
-        - section: Introduction
-           contents: 
-              - page: My Page
-                path: ./v2-2/pages/my-page.mdx # relative path to the file
-              - page: Shared Resource
-                path: ../shared-pages/shared-resource.mdx
-        - api: API Reference
-   - tab: help
-      contents: 
-         - section: Help Center
-           contents: 
-              - page: Contact Us
-                 path: contact-us.mdx
-```
-</CodeBlock>
-</CodeBlocks>
+<Markdown src="/snippets/version-specific-yml-files.mdx" />
 
 <Note>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/configuration/products).</Note>
 </Step>
 <Step title="Add your version configuration">
 
-To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`. 
-
-```bash
-fern/
-  ├─ fern.config.json
-  ├─ generators.yml
-  ├─ docs.yml
-  └─ versions/
-    ├─ ...
-    ├─ v2-1.yml
-    └─ v2-2.yml
-```
+Define a version in the top-level `docs.yml` by adding an item to the `versions` list and specifying the `display-name` and `path`. 
 
 <CodeBlock title="docs.yml">
 ```yaml
 versions: 
-  - display-name: v2.2          # shown in the dropdown
-    path: ./versions/v2-2.yml   # relative path to the version file
-  - display-name: v2.1
-    path: ./versions/v2-1.yml
+  - display-name: Latest          # shown in the dropdown
+    path: ./versions/latest.yml   # relative path to the version file
+  - display-name: V2
+    path: ./versions/v2.yml
 ```
 </CodeBlock>
 </Step>
 <Step title="Indicate availability">
 
-You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. 
+<Markdown src="/snippets/version-availability.mdx" />
 
 <CodeBlock title="docs.yml">
 ```yaml {4}
 versions: 
-  - display-name: v2.2          
-    path: ./versions/v2-2.yml   
+  - display-name: Latest          
+    path: ./versions/latest.yml   
     availability: beta
-  - display-name: v2.1
-    path: ./versions/v2-1.yml
+  - display-name: v2
+    path: ./versions/v2.yml
     availability: stable
 ```
 </CodeBlock>
 
-Version availability is distinct from [section and page availability](/learn/docs/configuration/navigation#section-and-page-availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files.
-
 </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 version-specific `.yml` files. 
 </Step>
-</Steps>
+</Steps>
+
+## Customize version selector styling
+
+You can directly customize the appearance of the version selector by targeting the `fern-version-selector` CSS class.
+
+### Common styling adjustments
+
+<Markdown src="/snippets/common-selector-styling.mdx" />
+
+```css
+.fern-version-selector {
+  transform: translateY(1px);
+  border-radius: 1000px;
+  border: 1px solid var(--border);
+}
+```
+
+### Customize the dropdown
+
+The dropdown menu for the version selector can be customized using the `fern-version-selector-radio-group` CSS class.
+
+  <Frame>
+    <img src="webflow-version-selector.avif" alt="Example of a styled version selector" />
+  </Frame>

fern/snippets/common-selector-styling.mdx

@@ -0,0 +1,5 @@
+**Adjusting positioning:**
+Use `transform: translateY(Npx)` to adjust the vertical positioning of the selectors. This ensures that the selectors match the line height of your logo for better visual alignment.
+
+**Enhancing visual prominence:**
+You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site's design aesthetic.

fern/snippets/version-availability.mdx

@@ -0,0 +1,3 @@
+You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. 
+
+Version availability is distinct from [section and page availability](/learn/docs/configuration/navigation#section-and-page-availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files.

fern/snippets/version-specific-yml-files.mdx

@@ -0,0 +1,42 @@
+<CodeBlocks>
+<CodeBlock title="latest.yml">
+```yaml
+navigation: 
+  - section: Introduction
+    contents: 
+      - page: My Page
+        path: ./latest/pages/my-page.mdx  # relative path to the file
+      - page: Shared Resource
+        path: ../shared-pages/shared-resource.mdx
+  - api: API Reference
+```
+</CodeBlock>
+<CodeBlock title="v2.yml">
+```yaml
+tabs: 
+  api: 
+    title: API Reference
+    icon: puzzle
+  help:
+    title: Help Center
+    icon: home
+
+ navigation:
+  - tab: api
+     contents:
+        - section: Introduction
+           contents: 
+              - page: My Page
+                path: ./v2/pages/my-page.mdx # relative path to the file
+              - page: Shared Resource
+                path: ../shared-pages/shared-resource.mdx
+        - api: API Reference
+   - tab: help
+      contents: 
+         - section: Help Center
+           contents: 
+              - page: Contact Us
+                 path: contact-us.mdx
+```
+</CodeBlock>
+</CodeBlocks>