From 410cdc71e86b2815f32b8bb6e498877daf9cf4b9 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:06:54 +0000 Subject: [PATCH 1/8] docs: document git-ref-based docs versioning Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/changelog/2026-08-06.mdx | 16 +++++++++++++ .../docs/pages/navigation/versions.mdx | 23 +++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 fern/products/docs/pages/changelog/2026-08-06.mdx diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx new file mode 100644 index 000000000..ebb0b39da --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -0,0 +1,16 @@ +## Build a docs version from a git ref + +navigation, docs.yml + +You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's pages, navigation, assets, and API definitions from the ref, composed with the current branch's theme and shell. Use it for snapshot versions that are frozen at a release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. + +```yaml docs.yml {5} +versions: + - display-name: Latest + path: ./versions/latest.yml + - display-name: v2 + ref: v2.0.0 + availability: deprecated +``` + + diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 1505319d5..4f89f96c4 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -87,6 +87,29 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure +## Build a version from a git ref + +Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, API definitions, and committed library output from it, composed with the current branch's theme, shell, and `versions` metadata. + + +```yaml {5} +versions: + - display-name: Latest + path: ./versions/latest.yml # built from the working tree + - display-name: v2 + ref: v2.0.0 # built from the tag v2.0.0 + availability: deprecated +``` + + +A version entry sets either `path` or `ref`, never both. Declaring both fails `fern check`. + +Git refs suit snapshot versioning: releases that are frozen at a point in time and no longer receive content updates. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. + +Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. + +At the ref, Fern builds the navigation from that commit's `versions[0].path`, falling back to its top-level `navigation`. The ref's own `versions` list isn't followed, so older versions declared there are ignored. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. + ## Customize version behavior These optional settings let you control how versions appear in URLs and who can access them. From 4fd1354375180c9aaa79c26944812e4b7e10d1f3 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:11:42 +0000 Subject: [PATCH 2/8] docs: simplify git ref build description Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/changelog/2026-08-06.mdx | 2 +- fern/products/docs/pages/navigation/versions.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx index ebb0b39da..c7358dcfc 100644 --- a/fern/products/docs/pages/changelog/2026-08-06.mdx +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -2,7 +2,7 @@ navigation, docs.yml -You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's pages, navigation, assets, and API definitions from the ref, composed with the current branch's theme and shell. Use it for snapshot versions that are frozen at a release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. +You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's content from the ref, composed with the current branch's theme and shell. Use it for snapshot versions that are frozen at a release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. ```yaml docs.yml {5} versions: diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 4f89f96c4..e57858b5b 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -89,7 +89,7 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure ## Build a version from a git ref -Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, API definitions, and committed library output from it, composed with the current branch's theme, shell, and `versions` metadata. +Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's content from it, composed with the current branch's theme, shell, and `versions` metadata. ```yaml {5} From f5e054ec1d1ab16c2c0f26415c7bc8a676d578e9 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:12:35 +0000 Subject: [PATCH 3/8] docs: use 'frozen versions' instead of 'snapshot versioning' Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/changelog/2026-08-06.mdx | 2 +- fern/products/docs/pages/navigation/versions.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx index c7358dcfc..e4111d83f 100644 --- a/fern/products/docs/pages/changelog/2026-08-06.mdx +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -2,7 +2,7 @@ navigation, docs.yml -You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's content from the ref, composed with the current branch's theme and shell. Use it for snapshot versions that are frozen at a release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. +You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's content from the ref, composed with the current branch's theme and shell. Use it for frozen versions archived at a past release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. ```yaml docs.yml {5} versions: diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index e57858b5b..0d77928a5 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -104,7 +104,7 @@ versions: A version entry sets either `path` or `ref`, never both. Declaring both fails `fern check`. -Git refs suit snapshot versioning: releases that are frozen at a point in time and no longer receive content updates. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. +Git refs suit frozen versions: past releases that are archived at a point in time and no longer receive content updates. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. From 305a279f69a284fa66bd5abf59dd402f894eb997 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:13:08 +0000 Subject: [PATCH 4/8] docs: describe ref content root in user terms Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/navigation/versions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 0d77928a5..98e35eb80 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -108,7 +108,7 @@ Git refs suit frozen versions: past releases that are archived at a point in tim Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. -At the ref, Fern builds the navigation from that commit's `versions[0].path`, falling back to its top-level `navigation`. The ref's own `versions` list isn't followed, so older versions declared there are ignored. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. +If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. ## Customize version behavior From 67d6c50db84499f7e3ca1f93f5896ed4c6f34e33 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:41:14 +0000 Subject: [PATCH 5/8] docs: add branch ref example; drop path/ref exclusivity note Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/navigation/versions.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 98e35eb80..afe5cdb57 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -92,18 +92,18 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's content from it, composed with the current branch's theme, shell, and `versions` metadata. -```yaml {5} +```yaml {5,8} versions: - display-name: Latest path: ./versions/latest.yml # built from the working tree - display-name: v2 - ref: v2.0.0 # built from the tag v2.0.0 + ref: release/v2 # built from the branch release/v2 + - display-name: v1 + ref: v1.0.0 # built from the tag v1.0.0 availability: deprecated ``` -A version entry sets either `path` or `ref`, never both. Declaring both fails `fern check`. - Git refs suit frozen versions: past releases that are archived at a point in time and no longer receive content updates. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. From e87a1e3ed54c7a0ea38f21f496c5ce206ebb0c74 Mon Sep 17 00:00:00 2001 From: "ryan.stephen" Date: Thu, 6 Aug 2026 18:42:04 +0000 Subject: [PATCH 6/8] docs: trim shallow-checkout and library-output details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/navigation/versions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index afe5cdb57..60e5ff395 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -108,7 +108,7 @@ Git refs suit frozen versions: past releases that are archived at a point in tim Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. -If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. +If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote. ## Customize version behavior From 6f83a80b4529bdfbf8ed13180db01c407957477a Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Thu, 6 Aug 2026 20:16:56 +0000 Subject: [PATCH 7/8] docs: replace 'frozen versions' with plain description Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/changelog/2026-08-06.mdx | 2 +- fern/products/docs/pages/navigation/versions.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx index e4111d83f..730d7dd68 100644 --- a/fern/products/docs/pages/changelog/2026-08-06.mdx +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -2,7 +2,7 @@ navigation, docs.yml -You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's content from the ref, composed with the current branch's theme and shell. Use it for frozen versions archived at a past release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. +You can now point a version entry at a git `ref` (a branch, tag, or commit SHA) instead of a `path` in your working tree. On publish, Fern builds that version's content from the ref, composed with the current branch's theme and shell. Use it for a version that no longer receives content updates, such as a past release; keep actively maintained versions on `path`, since `fern docs dev` previews working-tree versions only. ```yaml docs.yml {5} versions: diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 60e5ff395..61bb0d73f 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -104,7 +104,7 @@ versions: ``` -Git refs suit frozen versions: past releases that are archived at a point in time and no longer receive content updates. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. +Use a `ref` for a version of your docs that no longer receives content updates, such as a past release. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. From baf09e2239e9a0ec9d1accbdd23c7c6fdf09b888 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 6 Aug 2026 16:23:46 -0400 Subject: [PATCH 8/8] reorganize content a bit --- .../docs/pages/navigation/versions.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index 61bb0d73f..307f45239 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -61,6 +61,8 @@ versions: ``` +`path` points at a version file in your working tree. A version whose content lives at a git [branch, tag, or commit](#build-a-version-from-a-git-ref) can name a `ref` instead. + @@ -87,7 +89,12 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure -## Build a version from a git ref +## Customize version behavior + +These optional settings let you control where each version's content comes from, how versions appear in URLs, and who can access them. + + + Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's content from it, composed with the current branch's theme, shell, and `versions` metadata. @@ -104,17 +111,13 @@ versions: ``` -Use a `ref` for a version of your docs that no longer receives content updates, such as a past release. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Treat `ref` as the alternative to long-lived version branches, letting your `main` branch hold the current docs plus the full version list while historical releases stay archived at their tags. +Use a `ref` for a version of your docs that no longer receives content updates, such as a past release. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing. Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. -If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote. +If the ref's own `docs.yml` is versioned, Fern builds its default version and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing a ref-backed version requires git and access to the remote. -## Customize version behavior - -These optional settings let you control how versions appear in URLs and who can access them. - - + By default, Fern generates URL slugs from the `display-name` by converting it to lowercase and replacing spaces with hyphens. For example, a version with `display-name: v3 (Deprecated)` would get the slug `v-3-deprecated` in the URL path.