Merge branch 'main' into chdeskur/api-key-injection

fern/docs.yml

@@ -341,6 +341,9 @@ navigation:
           - page: Navigation
             icon: fa-regular fa-compass
             path: ./pages/docs/building-your-docs/navigation.mdx
+          - page: Versioning
+            icon: fa-regular fa-code-branch
+            path: ./pages/docs/building-your-docs/versioning.mdx
           - page: Announcement Banner
             icon: fa-regular fa-bullhorn
             path: ./pages/docs/building-your-docs/announcement-banner.mdx
@@ -467,9 +470,6 @@ navigation:
           - page: Write Markdown in API Reference
             icon: fa-regular fa-pencil
             path: ./pages/fern-docs/content/api-ref-content.mdx
-          - page: Customize API Playground
-            icon: fa-regular fa-square-terminal
-            path: ./pages/fern-docs/content/customize-api-playground.mdx
 
       - section: Integrations
         slug: integrations

fern/pages/docs/building-your-docs/navigation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configure your site navigation
-description: Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, versions, and more.
+description: Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.
 ---
 
 ## Use `docs.yml`
@@ -179,58 +179,5 @@ Here's an example of what the Tabs implementation looks like:
 
 ## Versions
 
-If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`.
+If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning). 
 
-<Frame>
-![A dropdown of the available versions](https://fern-image-hosting.s3.amazonaws.com/versions.png)
-</Frame>
-
-When adding an entry to the `versions` list, specify the version's `display-name`, which is visible to users, and `path`, which is a file that must be in a folder called `versions/`:
-
-<CodeBlock title="docs.yml">
-```yaml
-versions: 
-  - display-name: v1.0
-      path: v1-0.yml # must be in a `versions` folder
-  - display-name: v1.1
-      path: v1-1.yml
-```
-</CodeBlock>
-
-<CodeBlock title="versions/v1-0.yml">
-```yaml
-navigation: 
-  - section: Introduction
-    contents: 
-      - page: My Page
-        path: my-page.mdx
-  - api: API Reference
-```
-</CodeBlock>
-
-<CodeBlock title="versions/v1-1.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: my-page.mdx
-        - api: API Reference
-   - tab: help
-      contents: 
-         - section: Help Center
-           contents: 
-              - page: Contact Us
-                 path: contact-us.mdx
-```
-</CodeBlock>

fern/pages/docs/building-your-docs/versioning.mdx

@@ -0,0 +1,103 @@
+---
+title: Versioning
+subtitle: Allow users to navigate between different versions of your docs. 
+---
+
+<Frame>
+![A dropdown of the available versions](versions.png)
+</Frame>
+
+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:**
+
+<Steps>
+### 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. 
+
+```bash
+fern/
+  ├─ fern.config.json
+  ├─ generators.yml
+  ├─ docs.yml
+  ├─ pages/
+    ├─ ...
+  └─ versions/
+    ├─ v2-1/pages/...
+    ├─ v2-1.yml
+    ├─ v2-2/pages/...
+    └─ v2-2.yml
+```
+
+<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>
+
+### 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
+```
+
+<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
+```
+</CodeBlock>
+
+### 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. 
+</Steps>

fern/pages/fern-docs/content/customize-api-playground.mdx

@@ -1,6 +1,6 @@
 ---
-title: Customize your API Playground
-description: Customize your API Playground Settings
+title: Advanced configuration
+description: Configure advanced settings like the server URLs reachable by the API playground and authentication with OAuth.
 ---
 
 If you subscribe to Fern's Pro or Enterprise Plans, you can customize your API Playground settings to suit your customers needs.