Document availability for sections, pages, versions, and APIs (#769)

devalog · web-flow · commit 1e80cf5664a7 · 2025-09-11T20:21:21.000-04:00
diff --git a/fern/products/api-def/ferndef-pages/availability.mdx b/fern/products/api-def/ferndef-pages/availability.mdx
@@ -3,15 +3,17 @@ title: Availability in Fern Definition
 description: Add availability to Fern Definition API services, endpoints, types, or properties to indicate their release status.
 ---
 
-You can add `availability` to an endpoint, type, or property within your Fern Definition.
+You can add `availability` to an endpoint, type, or property within your Fern Definition. You can configure the `availability` of sections in your API reference documentation in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml). 
+
+## Endpoints, types, and properties
 
 Availability can be:
 - `in-development` which means it is being worked on; will show a `Beta` tag
 - `pre-release` which means it is available; will show a `Beta` tag
 - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag
 - `generally-available` which means it is stable and available for use; will show a `GA` tag
 
-## Endpoint 
+### Endpoint 
 
 <CodeBlock title="pet.yml">
 ```yaml {6}
@@ -36,7 +38,7 @@ In Fern Docs, this will look like:
 ![Screenshot showing a deprecated tag next to an endpoint in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/endpoint-deprecated.png)
 </Frame>
 
-## Type
+### Type
 
 <CodeBlock title="pet.yml">
 ```yaml {15}
@@ -69,7 +71,7 @@ In Fern Docs, this will look like:
 ![Screenshot showing a beta tag next to a type in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/type-beta.png)
 </Frame>
 
-## Property 
+### Property 
 
 <CodeBlock title="pet.yml">
 ```yaml {12}
@@ -94,3 +96,7 @@ In Fern Docs, this will look like:
 <Frame>
 ![Screenshot showing a deprecated tag next to a type's property in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png)
 </Frame>
+
+## Sections
+
+<Markdown src="/snippets/availability.mdx" />
diff --git a/fern/products/api-def/openapi-pages/extensions/availability.mdx b/fern/products/api-def/openapi-pages/extensions/availability.mdx
@@ -3,7 +3,11 @@ title: Availability
 description: Mark endpoint availability status using `x-fern-availability` extension
 ---
 
-The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags.
+The `x-fern-availability` extension is used to mark the availability of an endpoint within your OpenAPI definition. The availability information propagates into the generated Fern Docs website as visual tags. 
+
+You can configure the `availability` of sections in your API reference documentation in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml). 
+
+## Endpoint
 
 The options are:
 
@@ -24,4 +28,8 @@ This renders as:
 
 <Frame caption="A deprecated endpoint">
 ![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png)
-</Frame>
+</Frame>
+
+## Section
+
+<Markdown src="/snippets/availability.mdx" />
diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -176,7 +176,7 @@ You can hide an endpoint from the API reference by setting `hidden` to `true`. T
 </Tabs>
 
 ### Adding custom sections
-You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), and `contents`. 
+You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), `availability`, and `contents`. 
 
 <Tabs>
   <Tab title="OpenAPI Specification">
@@ -240,3 +240,23 @@ navigation:
             - link: Link Title
               href: http://google.com
 ```
+
+### Adding availability
+
+You can set the availability for the entire API reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
+
+```yaml title="docs.yml" {3, 6}
+navigation: 
+  - api: API Reference
+    availability: generally-available
+    layout: 
+      - section: My Section
+        availability: beta
+        icon: flower
+        contents: 
+        # endpoints here
+```
+
+When you set availability for a section, all endpoints in that section will inherit the section-level availability unless explicitly overridden in your API definition.
+  
+<Warning>You can't set availability for individual endpoints in `docs.yml`. Endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability).</Warning>
diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx
@@ -21,6 +21,7 @@ navigation:
 | `api` (required) | Title of the API Reference Section                                                                      |
 | `api-name`       | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference)  |
 | `audiences`      | List of [audiences](/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference          |
+| `availability`   | Set the [availability status](/learn/docs/api-references/customize-api-reference-layout#adding-availability) for the entire API Reference or specific sections                           |
 | `display-errors` | Displays error schemas in the API References                                                            |
 | `snippets`       | Enable [generated SDK code snippets](/learn/api-reference/snippets/get) in your API Reference            |
 | `summary`        | Relative path to the Markdown file; the summary is displayed at the top of the API section              |
diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx
@@ -97,6 +97,32 @@ navigation:
         path: ./pages/also-hidden.mdx
 ```
 
+### Section and page availability
+
+You can set availability for individual pages or entire sections. When you set availability for a section, all pages within that section inherit the same availability unless explicitly overridden at the page level.
+
+Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
+
+```yaml Availability {3, 11, 14}
+navigation:
+  - section: Developer Resources
+    availability: generally-available
+    contents:
+      - page: Code Examples # Inherits generally-available
+        path: ./pages/code-examples.mdx
+      - page: CLI Tools # Inherits generally-available
+        path: ./pages/cli-tools.mdx
+      - page: Testing Framework
+        path: ./pages/testing-framework.mdx
+        availability: beta # Overrides section-level availability
+      - page: Performance Monitoring
+        path: ./pages/performance-monitoring.mdx
+        availability: in-development # Overrides section-level availability
+```
+<Note>
+  If you have different versions of your docs, section and page availability should be set in [the `.yml` files that define the navigational structure for each version](/learn/docs/configuration/versions#define-your-versions).
+</Note>
+
 ## Section overviews
 
 To add an overview page to a section, add a `path` property to the section.
diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx
@@ -143,7 +143,7 @@ In the below example, Product A is **unversioned** and Product B is **versioned*
 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-17}
+```yaml {2, 8, 13-19}
 products:
   - display-name: Product A # unversioned
     path: ./products/product-a.yml
@@ -159,8 +159,10 @@ products:
     versions: # optional
       - display-name: Latest
         path: ./products/product-b/latest.yml
+        availability: beta
       - display-name: V2
         path: ./products/product-b/v2.yml
+        availability: ga
 ```
 </CodeBlock>
 
diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx
@@ -104,6 +104,25 @@ versions:
     path: ./versions/v2-1.yml
 ```
 </CodeBlock>
+</Step>
+<Step title="Indicate availability">
+
+You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. 
+
+<CodeBlock title="docs.yml">
+```yaml {4}
+versions: 
+  - display-name: v2.2          
+    path: ./versions/v2-2.yml   
+    availability: beta
+  - display-name: v2.1
+    path: ./versions/v2-1.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">
 
diff --git a/fern/snippets/availability.mdx b/fern/snippets/availability.mdx
@@ -0,0 +1,15 @@
+You can set the availability for the entire API reference or for specific sections in your `docs.yml` configuration. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
+
+When you set the availability of a section, all of the endpoints in that section are automatically marked with that availability unless explicitly set otherwise. 
+
+```yaml title="docs.yml" {3, 6}
+navigation: 
+  - api: API Reference
+    availability: generally-available
+    layout: 
+      - section: My Section
+        availability: beta
+        icon: flower
+        contents: 
+        # endpoints here
+```
