Changelog

(fix): Decouple SDK Config initialization from SDK Gen API generation routing so each can be rolled out independently.

(fix): fern docs md generate now prefixes generated Python library page slugs with the slug of the navigation tab the pages are listed under in docs.yml. Generated pages previously skipped the tab (e.g. /prismo/prismo/floorplan_editor_signals instead of /api-reference/prismo/prismo/floorplan_editor_signals). File paths and page IDs are unchanged.

(fix): fern generate --docs no longer re-parses every OpenAPI spec of an API reference that sets tag-description-pages: true. Tag descriptions are now read straight from the specs’ tags, which saves about 0.4s per spec on a large (4.8 MB) spec.

(fix): OpenAPI specs with external $refs to remote files convert faster. Each remote file is now fetched once per conversion instead of once per $ref (for example 114 fetches down to 2 on a large spec), and a failed fetch is retried by the next $ref instead of being remembered.

(feat): Add an experimental fern docs dev --astro flag that renders the docs to the ledger read model, serves it from a local mirror, and runs the prebuilt Astro docs preview server (downloaded and cached like the Next bundle) against it with live reload. Next.js remains the default.

(fix): fern generate --local now generates SDK Config targets after fern sdk migrate, instead of failing with “SDK Config v1 generation is only supported with remote sdk-gen-api generation” (--target) or silently generating nothing (no selectors). Each target runs on the on-prem generator for its language, at its generatorVersion or, when unpinned, the SDK Config cutover release. Targets with zip or github delivery generate into generated/<language> beside sdk-config.yml. Targets with no on-prem generator, a pre-cutover generatorVersion, or a repeated language, and an --sdk-config file other than the one the local runner reads (sdk-config.yml, else sdk-config.yaml), are rejected with an explanation.

(fix): fern check now reads and validates each markdown page once, even when several navigation items or version files reference it. A page shared by 36 versions is no longer parsed and link-checked 36 times, and its errors are reported once instead of once per reference.

(fix): fern generate --docs uses less memory on large multi-version API references. Worker threads return their dynamic snippet IRs gzipped, the IRs cached for validation are released once the docs navigation is built, and each worker’s heap is capped at 1.5 GB (a job that runs out of memory is regenerated in-process). Machines with less than about 9.5 GB of RAM, such as the 2-core / 7 GB GitHub Actions runner, keep generating dynamic snippet IRs in-process.

(fix): fern generate --docs is faster on large multi-version API references. OpenAPI parsing no longer rescans the whole spec for every operation’s request body, type resolution no longer rebuilds the map of definition files on every lookup while generating dynamic snippet IRs, and external $ref resolution no longer re-shifts its work queue. Dynamic snippet IRs are now generated on worker threads (bounded by CPU cores, available memory and FERN_DOCS_API_REGISTRATION_CONCURRENCY; runners with less than about 10 GB of RAM, such as the 2-core GitHub Actions runner, stay in-process), starting as soon as each API’s IR is built so they overlap the navigation build. Set FERN_DOCS_API_REGISTRATION_CONCURRENCY=1 to generate them serially in-process.

(fix): Fix translated navigation labels getting out of order after a top-level page, link, or collapsed section. The CLI wraps those items in an internal sidebar group, and the translation overlay now matches the group’s items as siblings of the items around it, so labels like API reference sections and endpoint titles no longer stay in English or pick up another item’s translation.

(fix): fern generate --docs now registers each distinct API definition once per publish. Versioned docs that reference the same API from every version no longer repeat its AI example enhancement, dynamic snippet generation and upload for each version.

(fix): fern generate --docs now builds each OpenAPI workspace’s IR once per run. The publish reuses the IR that the valid-markdown-links check already built, instead of converting every spec a second time.

(fix): Fix component schemas that are only a $ref to another schema (for example CopyBatchArg: { $ref: '#/components/schemas/RelocationBatchArgBase' }) being imported as unknown. Their API reference pages showed “any” instead of the referenced type’s fields. These schemas now become an alias of the referenced type.

(fix): fern generate --docs now registers API definitions with FDR four at a time instead of one after another, which shortens publishes for docs sites with many APIs or API versions. Set FERN_DOCS_API_REGISTRATION_CONCURRENCY to change the limit (1 restores serial registration).

(fix): <Markdown src="..." /> snippets now resolve when a prop value contains >, e.g. <Markdown src="/snippets/intro.mdx" returnType="Promise<void>" />. Previously the > inside the quoted value ended the tag early, so the snippet was never inlined and the page rendered incorrectly.

(feat): fern init can now create sdk-config.yml for new OpenAPI projects. Initialized OpenAPI files are bundled into the Fern workspace, while URL sources are preserved in the generated configuration.

(fix): Fix fern generate --docs corrupting MDX pages that mix JSX image expressions like icon={<img src="..." />} with other components that have local image paths. Text after those components (such as a closing </Tab>) was deleted, so the page failed to compile and rendered as raw text.

(fix): Fix local images inside Markdown link text, like [Docs <img src="./icon.svg" />](https://...) or [![badge](./badge.png)](https://...), being published with the build machine’s absolute path instead of the uploaded file. Finding images to upload no longer parses each page as full MDX, which makes fern generate --docs faster on large sites.

(fix): Support building package artifacts from SDKs generated through SDK Gen API with fern generate --package, including pnpm-based TypeScript projects.

(feat): SDK variables can now declare an environment variable fallback. In api.yml, use the detailed form variables: { myVar: { type: string, env: MY_VAR } }; in OpenAPI, add x-fern-env: MY_VAR to an x-fern-sdk-variables entry. The value is emitted as VariableDeclaration.envVar in the IR so generators can make the variable optional at client construction and read it from the environment when it is not passed explicitly.

(fix): fern org get now names the org, shows when the CLI version policy was last updated, and shows the running CLI version (e.g. Org "acme" requires Fern CLI >= 5.106.0 (updated 2026-08-26). You're on 5.140.2.), so the output no longer reads like an error.

(fix): fern upgrade no longer warns that the running CLI is outside the org’s version policy (“Version redirection is disabled, so it was not upgraded”), since the upgrade itself moves the project to a new version.

(fix): fern docs dev no longer reports a false api-section-has-definition error for every api: navigation item. The dev server validates docs without loading API workspaces, so the check is now skipped there; fern check and fern generate --docs still run it.

(fix): Upgrade to SDK Config 0.6 and omit defaulted optional fields from SDK Config payloads sent to local and remote generators.

(feat): fern export now accepts a repeatable --audience flag. When set, the exported OpenAPI spec only includes the endpoints, webhooks, environments, and schemas required for those audiences (e.g. fern export openapi.yml --audience public).

(fix): fern generate --docs --preview --id <id> --no-prompt no longer asks for confirmation when the preview ID already exists, so an existing preview can be overwritten non-interactively (as --force and CI environments already allowed).

(fix): Fix several gaps in docs translation navigation overlays: the display-name of a changelog tab is now applied; overlays can now translate link labels, api reference titles, API package titles and endpoint titles (via the api node’s layout); positional matching of sections/pages no longer shifts after a sibling that was matched by an explicit slug; API layout section overlays now apply to their API package nodes; endpoint overlays match by HTTP method when it is unique among siblings; and multi-segment explicit overlay slugs (e.g. customization/voice) now match. Overlay endpoint titles are no longer reverted to the translated spec’s endpoint name when that name is unchanged from the default locale.