Changelog

5.10.1

(chore): Plumb the top-level replay block from generators.yml through the remote generation runner to the createJobV3 wire boundary, so cloud generation can honor replay.enabled once Fiddle exposes the field.

5.10.0

(fix): Fix self-hosted GitHub clone failing with “Invalid username or token” when the user’s ${GITHUB_TOKEN} is an OAuth user token (gho_) or personal access token (ghp_, github_pat_). The clone URL hardcoded the x-access-token: username, which is the format reserved for GitHub App installation tokens (ghs_). Now selects the format based on the token prefix, so both auth modes work.

(internal): Capture PostHog telemetry for replay outcomes during fern generate. Emits a single replay event with action: pipeline_run carrying patch counts, conflict reason buckets, generator/repo context, and pipeline duration. Honors FERN_DISABLE_TELEMETRY (v1) and FERN_TELEMETRY_DISABLED / ~/.fernrc (v2). Adds a structured [replay] info log line and per-bucket conflict debug counts so the same data is visible in stdout. No file paths, patch IDs, or commit messages are emitted; the SDK repo URI is hashed (sha256, 16-char prefix). Wires the previously-no-op v2 TaskContextAdapter.instrumentPostHogEvent so v2-driven generates feed the same event stream as v1. Distinguishes genuine replay crashes from flow: first-generation to keep success-rate dashboards honest.

5.9.0

(feat): Accept branch under github when mode is release in generators.yml. This allows users to configure a non-default branch for release mode in preparation for wiring the field through to the remote generation service.

5.8.2

(chore): Remove break from the supported changelog types so the automated release flow cannot produce a major version bump. Major releases must now be made by editing the relevant versions.yml directly so the breaking change is explicitly acknowledged in review. Validation rejects type: break in unreleased/.

5.8.1

(fix): Add a valid-changelog-slug rule to fern check that errors when a changelog’s effective URL slug is not one of the values served as an RSS/Atom/JSON feed by the docs platform (changelog, changelogs, release-notes, releasenotes, whats-new, whatsnew). Severity defaults to error and can be overridden via check.rules.valid-changelog-slug in docs.yml.

5.8.0

(feat): Add support for a custom robots.txt file in docs.yml. Set agents.robots-txt to a relative filepath and Fern will host the file at /robots.txt on your docs site, overriding the auto-generated default.

(fix): Show a clear, actionable error when the Fern GitHub App is not installed on the target repository instead of the generic “Failed to create job” message.

5.7.10

(fix): Fix the OpenAPI 3.1 -> IR converter to respect endpoint-level security: [] opt-outs when auth is configured in generators.yml. Previously, declaring an auth scheme at the workspace level would silently override every endpoint-level security field — including explicit empty-array opt-outs — so endpoints that intentionally opted out of auth (e.g. an OAuth token endpoint, or a public endpoint) ended up rendered in docs and SDKs as if they required the global auth scheme.

5.7.9

(fix): fern docs dev now fails with a clear error when no docs.yml is present, instead of exiting silently.

(fix): Fix section landing pages with skip-slug: true ignoring frontmatter slug declarations. Sections now compute separate slugs for the overview page (honors frontmatter) and for children (respects skip-slug), so both features work correctly together.

5.7.8

(fix): Fix fern logout showing a “localhost refused to connect” error page by starting a local server to serve a branded confirmation page, matching the login flow. Also update both login and logout confirmation pages with new branded designs.

5.7.7

(chore): Reduce verbose logging during OpenAPI parsing by moving individual example validation warnings to debug level. The per-API example validation summary is still shown at warn level.

(fix): Improve logging when APIs are skipped during docs generation. Skipped APIs now log at error level (instead of warn) with the API name and a clear reason. Repetitive per-endpoint frontmatter warnings are aggregated into a single summary line per API.

5.7.6

(fix): Fix docs preview server showing “ready” message when the server process crashes on startup. The CLI now exits with a clear error message instead.

(fix): On Windows, recover critical standalone node_modules packages (next, react-dom, styled-jsx) when symlink resolution fails due to long .pnpm directory names. The CLI now scans the .pnpm store and copies packages directly as a fallback.

5.7.5

(fix): Send customDomains when publishing docs translations so FDR mirrors the translated blob to every URL the docs are published to. Previously translations were only written under the canonical fern URL, so docs sites served from a custom domain with a basepath (e.g. buildwithfern.com/learn) 404’d on every localized page.

5.7.4

(fix): Strip Windows drive letter prefixes from resolved image paths in docs preview to prevent raw filesystem paths from leaking into rendered HTML on Windows.

5.7.3

(fix): Fix image path resolution on Windows for fern docs dev and fern generate docs. Path utilities (resolve, dirname, join) now normalize output to forward slashes, preventing file ID lookup mismatches caused by mixed path separators on Windows.

5.7.2

(fix): Allow BCP 47 locale tags (e.g. ja-JP, pt-BR, zh-Hans-CN) in the translations and languages fields of docs.yml. Previously these were rejected by the JSON-schema validator with must be one of [en, es, fr, ...].

5.7.1

(fix): Preserve OpenAPI default values for array schemas across query parameters, headers, request bodies, and response body properties so docs can render “Defaults to …” metadata for arrays.

5.7.0

(internal): cli-v2: introduce a shared stdin/stdout abstraction so commands uniformly honor the Unix - marker on I/O flags (stdin for inputs, stdout for outputs), with a “- used at most once per command” guard and a JSON-or-path input helper that parses inline JSON first and falls back to a file read.

(internal): cli-v2: fern api compile --output - now uses the shared stdio helper (behavior unchanged — still streams IR JSON to stdout).

(feat): cli-v2: fern sdk generate --api - and fern sdk preview --api - now read the OpenAPI/AsyncAPI spec from stdin (e.g. cat openapi.json | fern sdk generate --api - --org acme --target typescript --output ./sdk).

(feat): cli-v2: fern api split --output - prints the generated overlay/overrides for the matching spec to stdout as a preview, without modifying the workspace (no git-HEAD restore, no fern.yml updates). Requires --api to select a single spec.

5.6.1

(fix): Fix translated docs pages failing to resolve shared snippets (<Markdown src="..."/> and <Code src="..."/>). Snippet references are now resolved before registering translations, with locale-aware loading that prefers translated snippets (e.g., translations/zh/snippets/foo.mdx) when available.

5.6.0

(feat): Add fern automations upgrade command that wraps fern upgrade and fern generator upgrade into a single invocation with structured JSON output (--json). Designed for consumption by the fern-upgrade GitHub Action.

(fix): Replace brittle hardcoded changelog URL map in upgradeGenerator.ts with a regex-based derivation that supports all current and future generators.

5.5.1

(chore): Bump @fern-api/fdr-sdk to 1.2.0-1d73d2e141 to pick up the first-class Alpha, Preview, and Legacy availability values published from the fdr@1.2.0 tag.

5.5.0

(feat): Add alpha, beta, preview, and legacy as supported values for the x-fern-availability OpenAPI extension and the availability field in Fern Definitions. These flow through the IR to generators and docs.

(feat): Use first-class FDR Availability values (Alpha, Preview, Legacy) when converting IR to FDR, replacing the previous fallback mappings to Beta / Deprecated. Bumps @fern-api/fdr-sdk to a release that includes the new enum values.

5.4.3

(fix): Fix OpenAPI endpoints that declare only a 204 No Content success response being dropped during OpenAPI -> IR conversion. The user-defined 204 status code is now preserved on the endpoint response so docs display it correctly instead of falling back to a default 200.

5.4.2

(fix): Fix broken-links false positives for absolute links on sites that configure a basePath (e.g. https://docs.example.com/product). Page slugs are stored with the basePath prepended (product/about), but authors commonly write site-relative absolute links without it (/about, /v2/guide). The link validator now also checks the basePath-prefixed form so both conventions resolve.

5.4.1

(fix): Fix OpenAPI parsing crash when specs contain non-standard additionalProperties: "true" (string instead of boolean). The parser was attempting to use the in operator on a string value, causing a Cannot use 'in' operator to search for 'type' in true error.

(fix): Surface rule initialization errors in fern check instead of exiting silently. Previously, when a validation rule (e.g. valid-markdown-links) failed to initialize because its docs configuration could not be resolved — for example, a navigation folder: entry pointing at a path that does not exist — fern check would exit with code 1 and no visible error message. Now the underlying failure (e.g. Folder not found: …) is reported as a fatal violation on docs.yml.

5.4.0

(feat): Make auth optional at the service level in Fern Definition files. When omitted, auth is inherited from the root API-level auth scheme. This allows users to only specify auth: false when they explicitly want to disable auth.

5.3.0

(feat): Translation overlays can now override navbar links (CTAs) per locale. Set navbar-links: inside translations/<locale>/docs.yml and the per-locale FDR upload will use those instead of the docs-level navbar-links. Local icon files referenced from the overlay are uploaded and resolved alongside the rest of the docs assets.

5.2.2

(fix): Translated docs.yml overlays are now read directly from translations/<locale>/docs.yml, so an extra nested fern/ folder is no longer required. The legacy translations/<locale>/fern/docs.yml location continues to work as a fallback.

5.2.1

(fix): Fix auth scheme descriptions being lost when using generators.yml auth-schemes. When security schemes are overridden in generators.yml, Fern now preserves the descriptions from the OpenAPI spec’s components.securitySchemes instead of using generic placeholder text.

5.2.0

(feat): Add multi-source property to docs.yml instances configuration. When enabled, docs registration uses a basepath-aware S3 key format, allowing multiple independent doc sites to be hosted under the same custom domain with different basepaths. This replaces experimental.basepath-aware, which is now deprecated but still supported. When multi-source: true, the CLI validates that the url and custom-domain share the same basepath.

5.1.0

(internal): Introduce a simpler TtyAwareLogger local to cli-v2. The new logger drops legacy behaviours that cli-v2 did not use (omitOnTTY, FERN_SPINNER_STATUS, dynamic finish reassignment, ora dependency) and exposes a minimal register / write / takeOverTerminal / finish surface against a generic Paintable interface. Box-frame rendering moves into TaskGroup. The legacy TtyAwareLogger in @fern-api/cli-logger is untouched.

5.0.0

(break): Remove og:background-image metadata key. Use og:dynamic:background-image instead, which is consistent with other og:dynamic:* settings.

4.109.0

(feat): cli-v2: Add support for GraphQL specs in fern.yml. Specs can now be declared with a graphql key (plus optional name, origin, and overrides) and are rendered in the docs pipeline. SDK generation targets that reference an API containing a GraphQL spec emit a non-fatal warning and skip the GraphQL spec, since GraphQL SDK generation is not supported.

4.108.0

(internal): Validate staged changelog entries in changes/<version>/*.yml (not just versions.yml) and trigger the workflow on PRs that touch those staged files. Catches unescaped {} / <> / #{} patterns at PR time instead of after autorelease promotes the entry to versions.yml on main.

4.107.3

(fix): Fix fern generate --docs --preview hang when OpenAPI specs contain circular $ref chains. The unbundled fallback document now has its circular references replaced with opaque object schemas so downstream converters no longer infinite-loop.

4.107.2

(fix): Suppress additional Sentry false positives: EADDRINUSE port conflicts, MDX/acorn parse errors from docs preview and publishing, version range strings in generators.yml, missing fern project when using —id flag, non-JSON fern.config.json, and absolute filepath in OpenAPI spec config.

4.107.1

(fix): Make OpenAPI validation errors non-fatal during docs generation. Previously, validation issues like “Self-referencing circular pointer” or parameter name collisions would abort fern generate --docs entirely. The CLI now logs warnings and skips the offending API workspace so the rest of the docs can still be published. These validations remain errors in fern check.

4.107.0

(feat): Add infer-discriminated-union-base-properties OpenAPI parser setting. When enabled, the parser intersects the resolved (allOf-flattened) property maps of every variant of a discriminated oneOf and lifts properties that appear in all variants with structurally-equal schemas into the union’s common properties. SDKs (e.g. C#, Java, Go) that already support union base properties can then expose those shared fields directly on the union type without forcing callers to cast to a concrete variant. Defaults to false.

4.106.3

(fix): Send gitattributesEntries to Fiddle on fern replay init so the generated PR marks .fern/replay.lock as linguist-generated=true. Previously the entries were written into a temp clone that was discarded and never reached the server. Requires a matching Fiddle server change to consume the new field.

4.106.2

(fix): Translation no longer fails for an entire locale when a single MDX file has a parse error. Invalid pages are skipped with a warning that includes the file path, and the base page is used as a fallback.

4.106.1

(fix): Fix OpenAPI importer generating duplicate type names when an operation’s request body $refs a top-level components.schemas.X schema whose name collides with the auto-generated request wrapper name. The wrapper is now disambiguated by using “Body” instead of “Request” in the generated name.

4.106.0

(feat): Add support for translating navigation labels (tabs, products, versions, sections, pages, announcements) via YAML overlay files in translations/<lang>/fern/. The overlay files use the same format as write-translation output and are deep-merged over the source navigation configuration.

4.105.0

(fix): Fix branch creation during signed commit push in generator-cli. GitHub’s updateRef API returns 422 (not 404) when the target branch does not exist, so the createRef fallback was unreachable.

(feat): fern docs dev now exits with a hard error on Windows when long path support is not enabled, instead of printing a warning.

4.104.0

(chore): Improved translation logging by moving verbose page array output to debug level and formatting as a concise count instead of raw JSON array.

(feat): Support simplified string syntax for translations field in docs.yml. You can now use translations: [en, ja, fr] instead of requiring translations: [{lang: en}, {lang: ja}, {lang: fr}]. The verbose object syntax remains supported for specifying default: true.

4.103.1

(fix): Fix translation directory check to treat the first locale as the default when no explicit default: true is set, matching the behavior of the rest of the CLI.

4.103.0

(feat): Support BCP 47 locale tags (e.g. ja-JP, pt-BR, zh-Hans-CN) in the translations and languages fields of docs.yml. Previously only two-letter language codes were accepted.

4.102.0

(feat): Add validation to fern check / fern docs check that verifies all configured translation locales have a corresponding directory under fern/translations/. If a directory is missing, a clear error message is printed showing the expected directory structure.

4.101.0

(feat): Add websocket-oneof-display setting to docs.yml. When set to grouped, WebSocket messages with oneOf bodies are rendered as a single parent entry with nested variants instead of flattened separate entries (default: flat).

4.100.3

(fix): Fix fern generate --docs --preview to register translations for preview URLs. Previously, translation registration was skipped entirely in preview mode, causing translated docs to not appear in preview deployments.

4.100.2

(fix): Fix fern docs dev to serve translated page content when viewing localized pages.

4.100.1

(fix): Fix fern automations generate step summary not displaying SDK versions. Upgrade Fiddle SDK to consume the new actualVersion field from FinishedTaskStatus, which Fiddle now returns for both AUTO and explicit versioning modes. Falls back to log-regex parsing and locally-resolved version for backward compatibility.

(fix): Fix fern docs dev to serve translated page content when viewing localized pages.

4.100.0

(internal): Suppress Sentry false positives caused by user- and environment-provoked errors being misclassified as InternalError:

• Add a generic ErrnoException classifier in resolveErrorCode that maps filesystem errors (ENOENT, EACCES, ENOSPC, EPIPE, …) to EnvironmentError and network errors (ENOTFOUND, ECONNREFUSED, ETIMEDOUT, …) to NetworkError, both of which are non-reportable.
• Register an error listener on process.stdout/process.stderr in TtyAwareLogger to swallow EPIPE at the source before it reaches Sentry’s uncaught-exception integration (triggered when piping CLI output into head, jq, etc.).
• Make ContainerError non-reportable and replace the aggregate CliError({ ContainerError }) throw in the sdk generate and docs publish commands with TaskAbortSignal to prevent double-reporting individual task failures.
• Fix JsonError, ParseError, and GeneratorError class names surviving esbuild minification by explicitly setting this.name in their constructors, so isSchemaValidationError can reliably classify them as ParseError.
• Wrap yaml.load in loadOpenAPI to translate YAMLException into a user-readable CliError({ ParseError }) with file, line, and column context.
• Wrap swagger2openapi conversion failures in convertOpenAPIV2ToV3 as CliError({ ParseError }).
• Pass explicit ValidationError / NetworkError codes in createOrganizationIfDoesNotExist instead of letting them fall through to InternalError.
• Reclassify “Generator not found” in the upgrade message helper from InternalError to ConfigError (user’s generators.yml references an image not in FDR).
• Use TaskAbortSignal in rerunFernCliAtVersion failure path instead of reporting a spurious InternalError.

4.99.0

(feat): [Alpha] Add support for a translations block in docs.yml to configure multi-language documentation. Each entry specifies a locale (lang) and optionally marks it as the default language.

(fix): Include docs translation metadata in the docs definition published to FDR so generated fdr.json advertises configured locales alongside uploaded translation files.

4.98.0

(feat): Move docs theme commands (export, list, upload) from CLI v2 to CLI v1. Commands are now available as fern docs theme export, fern docs theme list, and fern docs theme upload. Uses DocsWorkspace for path resolution, v1 auth, and validates all file references before uploading.

4.97.0

(feat): [Alpha] Add support for a translations block in docs.yml to configure multi-language documentation. Each entry specifies a locale (lang) and optionally marks it as the default language.

(fix): Include docs translation metadata in the docs definition published to FDR so generated fdr.json advertises configured locales alongside uploaded translation files.

4.96.0

(feat): Add optional baseProperties field to UndiscriminatedUnionTypeDeclaration in the IR schema. Both the V3 importer and the legacy OpenAPI importer now extract sibling properties from oneOf/anyOf schemas and populate baseProperties on undiscriminated unions.

4.95.0

(feat): Add placeholder field to auth scheme configuration (basic, bearer, header) for controlling example values in dynamic code snippets. The fallback chain is: explicit placeholder > generic placeholder. Configurable via Fern definition YAML and OpenAPI extensions (x-fern-basic, x-fern-bearer, x-fern-header).