diff --git a/fern/products/api-def/ferndef-pages/availability.mdx b/fern/products/api-def/ferndef-pages/availability.mdx index 9e335ec12..bc11fde27 100644 --- a/fern/products/api-def/ferndef-pages/availability.mdx +++ b/fern/products/api-def/ferndef-pages/availability.mdx @@ -3,7 +3,9 @@ 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 @@ -11,7 +13,7 @@ Availability can be: - `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 ```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) -## Type +### Type ```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) -## Property +### Property ```yaml {12} @@ -94,3 +96,7 @@ In Fern Docs, this will look like: ![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) + +## Sections + + diff --git a/fern/products/api-def/openapi-pages/extensions/availability.mdx b/fern/products/api-def/openapi-pages/extensions/availability.mdx index 690249740..c18eae94c 100644 --- 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: ![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) - \ No newline at end of file + + +## Section + + \ No newline at end of file diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 60c652f94..15fa529fc 100644 --- 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 ### 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`. @@ -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. + +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). diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index b14c1caa6..e91b5d6a1 100644 --- 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 index f13986454..25a7ffd09 100644 --- 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 +``` + + 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). + + ## 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 index bd574f257..4406fc3b3 100644 --- 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: -```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 ``` diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index d4ad83915..c7fc0bb46 100644 --- 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 ``` + + + +You can optionally set the availability status for each version. Options are `deprecated`, `ga`, `stable`, and `beta`. + + +```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 +``` + + +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. + diff --git a/fern/snippets/availability.mdx b/fern/snippets/availability.mdx new file mode 100644 index 000000000..86d143909 --- /dev/null +++ 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 +``` \ No newline at end of file