diff --git a/fern/products/docs/pages/changelog/2025/6/5.mdx b/fern/products/docs/pages/changelog/2025/6/5.mdx new file mode 100644 index 000000000..df9990627 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 0e043d11a..715edcbba 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -86,85 +86,75 @@ tabs: -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 -If you provide both an `image` and an `icon`, the `image` will take precedence. - -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 -```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 ``` - - -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. +If you provide both an `image` and an `icon`, the `image` will take precedence. -In the below example, Product A is **unversioned** and Product B is **versioned**: + + - +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/... - ``` - + ├─ 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`: - -```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 ``` - -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). @@ -234,4 +224,4 @@ The dropdown menus for product and version selectors can be customized using the Example of a styled version selector - \ No newline at end of file + \ No newline at end of file