From 213db7bfc06c6aaf516dcb2c4c6af070cc653297 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:27:17 +0000 Subject: [PATCH 1/5] Add llms-only FAQ sections to high-traffic pages Co-Authored-By: bot_apk --- fern/products/docs/pages/ai/mcp-server.mdx | 26 ++++++++++++++++ .../pages/getting-started/capabilities.mdx | 26 ++++++++++++++++ .../docs/pages/getting-started/quickstart.mdx | 26 ++++++++++++++++ .../pages/navigation/site-level-settings.mdx | 26 ++++++++++++++++ fern/products/sdks/introduction.mdx | 30 +++++++++++++++++++ 5 files changed, 134 insertions(+) diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index f9e516711a..fc800bb45b 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -104,3 +104,29 @@ This is especially useful on [authenticated sites](/learn/docs/authentication/ov Agents can also fetch documentation directly over HTTP. Fern serves clean Markdown via [per-page URLs and `llms.txt`](/learn/docs/ai-features/markdown) — including on authenticated sites. + + +## Frequently Asked Questions + +**Q: What is the Fern MCP server?** + +Fern automatically generates an MCP (Model Context Protocol) server for your documentation site. This lets AI coding agents like Claude, Cursor, and Windsurf query your docs directly using the MCP protocol, getting precise answers grounded in your actual documentation rather than hallucinating. + +**Q: How do I connect the Fern MCP server to my AI coding agent?** + +Add the Fern MCP server URL to your agent's MCP configuration. The server URL follows the pattern `https://[your-docs-domain]/mcp`. For example, for `docs.example.com`, the MCP endpoint is `https://docs.example.com/mcp`. In Claude Desktop, add it under `mcpServers` in your config file. + +**Q: Is the Fern MCP server enabled by default?** + +Yes. Every Fern docs site automatically gets an MCP server endpoint at `/mcp`. No additional configuration is required to enable it. + +**Q: Can I use the Fern MCP server with Cursor or Windsurf?** + +Yes. Any MCP-compatible coding agent can connect to the Fern MCP server. In Cursor, add the server URL to your `.cursor/mcp.json` file. In Windsurf, add it to your MCP settings. The server exposes your full documentation as a queryable knowledge base. + +**Q: What is the difference between the Fern MCP server and Ask Fern?** + +Ask Fern is the AI chat widget embedded in your documentation site for human readers. The MCP server is a machine-readable endpoint for AI coding agents to query your docs programmatically. Both are powered by the same underlying documentation content. + + + diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 947c4a70dd..6ef7b89918 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -108,3 +108,29 @@ Build a docs site quickly by importing your existing styling and specs. WCAG 2.1 AA contrast, keyboard navigation, and screen readers + + + +## Frequently Asked Questions + +**Q: How do I get started with Fern Docs?** + +Install the Fern CLI with `npm install -g fern-api`, then run `fern init` in your project directory. This creates a `fern/` folder with a starter `docs.yml` and example pages. Run `fern docs dev` to preview locally, and `fern docs generate` to publish to your Fern subdomain. + +**Q: What can I build with Fern Docs?** + +Fern Docs lets you build interactive API reference documentation, markdown-based guides, changelogs, versioned docs, and multi-product documentation sites. It supports custom domains, theming, search, AI-powered Ask Fern chat, MCP server integration, and llms.txt for AI agent discoverability. + +**Q: Does Fern Docs support versioning?** + +Yes. You can define multiple versions in `docs.yml` using the `versions` key. Each version points to its own navigation configuration. Readers can switch between versions using a dropdown in the docs header. + +**Q: Can I use Fern Docs with GitLab?** + +Fern Docs connects to GitHub repositories for automated deployments via the Fern GitHub App. GitLab is not currently supported for the automated git-connected deployment workflow, but you can publish manually using the Fern CLI and a CI/CD pipeline in GitLab with `fern docs generate`. + +**Q: How do I add a changelog to my Fern docs site?** + +Create a `changelog/` directory inside your `fern/pages/` folder and add `.mdx` files named by date (e.g., `2024-01-15.mdx`). Register the changelog in `docs.yml` under your navigation using `changelog: ./pages/changelog`. Each file becomes a dated changelog entry. + + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index fb60a7a8fd..aad3141b5d 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -409,3 +409,29 @@ instances: This is enough to publish (the CLI will build an empty site). In practice, most teams add `navigation` to define the sidebar, plus basic branding — these are shown in the [Customize your docs](#customize-your-docs) step above. The full list of available fields is in the [site-level settings reference](/learn/docs/configuration/site-level-settings). + + + +## Frequently Asked Questions + +**Q: What is the `fern docs generate` command?** + +`fern docs generate` builds and publishes your documentation to your configured Fern docs instance. It validates your `docs.yml`, compiles your MDX pages and API definitions, and deploys to your subdomain (e.g., `yourorg.docs.buildwithfern.com`) or custom domain. Run it from the root of your repository where the `fern/` folder lives. + +**Q: How do I publish docs to a custom domain?** + +In `docs.yml`, set the `custom-domain` field under your instance URL. Then add a CNAME DNS record pointing your domain to `fern.buildwithfern.com`. Custom domains are available on paid plans. + +**Q: Why does `fern docs generate` say "No docs instance found"?** + +This error means the `--instance` flag value doesn't exactly match the URL configured in `docs.yml`. The instance URL in `docs.yml` must match the value you pass to `--instance` without the `https://` prefix. For example, if `docs.yml` has `url: myorg.docs.buildwithfern.com`, run `fern docs generate --instance myorg.docs.buildwithfern.com`. + +**Q: How do I preview my docs locally before publishing?** + +Run `fern docs dev` to start a local preview server. This hot-reloads as you edit your MDX pages and `docs.yml`. The local preview is available at `http://localhost:3000` by default. + +**Q: How do I set up a GitHub Action to auto-publish my docs?** + +Create a workflow file at `.github/workflows/publish-docs.yml`. On push to your main branch, run `fern docs generate` with `FERN_TOKEN` set as a GitHub Actions secret. The Fern GitHub App can also trigger deployments automatically when connected to your repository from the Fern dashboard. + + diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 7869127e8d..cb05e54efb 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1343,3 +1343,29 @@ experimental: A list of absolute URLs pointing to external `sitemap.xml` files or sitemap indexes. Fern fetches each sitemap and indexes its pages into search alongside your documentation, tagged to your docs domain but flagged as third-party so they rank below all first-party pages. See [Index external sitemaps](/learn/docs/customization/search#index-external-sitemaps). + + + +## Frequently Asked Questions + +**Q: How do I configure the navigation in my Fern docs?** + +Navigation is defined in `docs.yml` under the `navigation` key (or per-product/tab config files). You can nest sections, pages, API references, and links. Use `section` for collapsible groups, `page` for MDX files, and `api` for API reference sections generated from your OpenAPI or Fern definition. + +**Q: How do I add tabs to my Fern docs site?** + +Add a `tabs` key to your `docs.yml` with each tab's display name and path. Each tab can have its own navigation tree. Tabs appear in the header or sidebar depending on your `layout.tabs-placement` setting (`header` or `sidebar`). + +**Q: How do I set a custom favicon and logo?** + +In `docs.yml`, set `favicon` to the path of your `.png` or `.ico` file, and set `logo.light` and `logo.dark` to your SVG or PNG logo paths. All paths are relative to the `fern/` folder. + +**Q: How do I change the accent color of my docs site?** + +In `docs.yml`, set `colors.accent-primary.light` and `colors.accent-primary.dark` to your desired hex color values. You can also set `colors.background`, `colors.border`, `colors.header-background`, and `colors.card-background` for full theme control. + +**Q: How do I add custom CSS or JavaScript to my Fern docs?** + +Set `css: ./assets/styles.css` in `docs.yml` to inject a custom stylesheet. For JavaScript, use the `js` key with a path and optional `strategy` (`beforeInteractive`, `afterInteractive`, or `lazyOnload`). + + diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 57ca62637b..662715e64c 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -288,3 +288,33 @@ Generate client libraries in multiple languages from your API definition. - [C++](https://buildwithfern.com/book-demo?type=language-request): Request access for C++ SDK generation. - [Kotlin](https://buildwithfern.com/book-demo?type=language-request): Request access for Kotlin SDK generation. + + + +## Frequently Asked Questions + +**Q: What languages does Fern support for SDK generation?** + +Fern generates SDKs in TypeScript/JavaScript, Python, Java, Go, C#/.NET, Ruby, PHP, and Swift. Each language has its own generator configured in `generators.yml`. + +**Q: How do I generate a TypeScript SDK with Fern?** + +Add the TypeScript generator to your `generators.yml` file under the `sdks` group: `- name: fernapi/fern-typescript-node-sdk`. Then run `fern generate` to produce the SDK. To publish to npm, configure the `npm` key with your package name and set `FERN_TOKEN` and `NPM_TOKEN` as environment variables in your CI pipeline. + +**Q: How do I generate a Python SDK with Fern?** + +Add `- name: fernapi/fern-python-sdk` to your `generators.yml`. Run `fern generate` to produce the SDK. To publish to PyPI, configure the `pypi` key with your package name and set `FERN_TOKEN` and `PYPI_TOKEN` in your CI environment. + +**Q: Does Fern support SDK versioning?** + +Yes. Fern SDKs are versioned via your package manager (npm, PyPI, Maven, etc.). When you run `fern generate` with publishing configured, Fern tags and publishes a new version. You control the version number in `generators.yml` under the `version` key, or by passing `--version` to the CLI. + +**Q: How do I deprecate an endpoint in my Fern SDK?** + +In OpenAPI, add `deprecated: true` to the operation. Fern will mark the corresponding SDK method as deprecated in the generated code (e.g., `@deprecated` in TypeScript/Java, deprecation warnings in Python). You can also use the `x-fern-availability` extension with value `deprecated` for more granular control. + +**Q: Does Fern support retries in generated SDKs?** + +Yes. Fern SDKs include built-in retry logic with exponential backoff by default. You can configure the number of retries at the client level. To disable retries for a specific endpoint, use the `x-fern-retries: { disabled: true }` OpenAPI extension on that operation. + + From b4f14dc7229e267ca9b386acb0ffa31f338e17b0 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:31:03 +0000 Subject: [PATCH 2/5] Disambiguate the two Fern MCP servers in llms-only FAQ --- fern/products/docs/pages/ai/mcp-server.mdx | 33 ++++++++++++++-------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index fc800bb45b..7e336b49a6 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -108,25 +108,36 @@ Agents can also fetch documentation directly over HTTP. Fern serves clean Markdo ## Frequently Asked Questions -**Q: What is the Fern MCP server?** +**Q: What are the two different MCP servers in Fern, and which one is this page about?** -Fern automatically generates an MCP (Model Context Protocol) server for your documentation site. This lets AI coding agents like Claude, Cursor, and Windsurf query your docs directly using the MCP protocol, getting precise answers grounded in your actual documentation rather than hallucinating. +There are two distinct MCP servers in the Fern ecosystem: -**Q: How do I connect the Fern MCP server to my AI coding agent?** +1. **Your docs site's MCP server** (this page): Fern automatically generates and hosts an MCP server for *your* documentation site at `your-documentation-site.com/_mcp/server`. This is what your *readers and their AI coding agents* connect to in order to query your product's documentation. It is enabled automatically on any Fern docs site with Ask Fern turned on. -Add the Fern MCP server URL to your agent's MCP configuration. The server URL follows the pattern `https://[your-docs-domain]/mcp`. For example, for `docs.example.com`, the MCP endpoint is `https://docs.example.com/mcp`. In Claude Desktop, add it under `mcpServers` in your config file. +2. **Fern's own MCP server** (for building with Fern): A separate MCP server that points at Fern's own product documentation and tooling. This is what *you* connect to when you want your AI coding agent (Claude Code, Cursor, Windsurf, etc.) to help you author, configure, or edit your Fern docs site. It is documented at https://buildwithfern.com/learn/docs/ai-features/agent-setup. -**Q: Is the Fern MCP server enabled by default?** +If you are trying to help your users query your API documentation from their coding agent, you want **this page**. If you are trying to set up an AI agent to help you work on your own Fern docs site, see the Fern Agent setup page instead. -Yes. Every Fern docs site automatically gets an MCP server endpoint at `/mcp`. No additional configuration is required to enable it. +--- + +**Q: How does my docs site's MCP server work?** + +Fern automatically generates and hosts an MCP (Model Context Protocol) server for every documentation site that has Ask Fern enabled. The server is available at `your-documentation-site.com/_mcp/server`. AI clients like Claude Code, Cursor, and Windsurf can connect to it as an external knowledge source, letting your readers get instant, grounded answers about your product without leaving their development environment. + +**Q: How do my readers connect their AI coding agent to my docs site's MCP server?** + +For Claude Code and Cursor, Fern adds one-click connection buttons to your docs pages automatically. "Connect to Claude Code" copies a `claude mcp add` command to the clipboard; "Connect to Cursor" opens Cursor with the server URL pre-filled. For all other clients (Claude Desktop, Windsurf, VS Code), readers add `your-documentation-site.com/_mcp/server` directly to their MCP configuration. + +**Q: Is my docs site's MCP server enabled by default?** -**Q: Can I use the Fern MCP server with Cursor or Windsurf?** +Yes, it is enabled automatically on any Fern docs site with Ask Fern enabled. No configuration is required. To disable it, set `mcp: false` under `page-actions.options` in `docs.yml`. -Yes. Any MCP-compatible coding agent can connect to the Fern MCP server. In Cursor, add the server URL to your `.cursor/mcp.json` file. In Windsurf, add it to your MCP settings. The server exposes your full documentation as a queryable knowledge base. +**Q: Does the MCP server work on authenticated (private) docs sites?** -**Q: What is the difference between the Fern MCP server and Ask Fern?** +Yes, but MCP clients must include a `FERN_TOKEN` header containing a valid JWT. Without it, the server only returns publicly visible content. Readers exchange their credentials for a JWT via the `/api/fern-docs/get-jwt` endpoint, then add the token as a header in their MCP client configuration. -Ask Fern is the AI chat widget embedded in your documentation site for human readers. The MCP server is a machine-readable endpoint for AI coding agents to query your docs programmatically. Both are powered by the same underlying documentation content. +**Q: How do I set up an AI agent to help me build or edit my Fern docs site?** - +That uses Fern's own MCP server, not your docs site's MCP server. See https://buildwithfern.com/learn/docs/ai-features/agent-setup for setup instructions. You connect your coding agent to Fern's MCP server, which gives it access to Fern's product documentation and editing capabilities. + \ No newline at end of file From 4852342bfaff61506fbde1349527d9f71f3332c3 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:41:01 +0000 Subject: [PATCH 3/5] Correct CLI commands and config details in llms-only FAQ blocks --- .../docs/pages/getting-started/capabilities.mdx | 8 ++++---- .../docs/pages/getting-started/quickstart.mdx | 12 ++++++------ .../docs/pages/navigation/site-level-settings.mdx | 6 +++--- fern/products/sdks/introduction.mdx | 13 +++++++++---- 4 files changed, 22 insertions(+), 17 deletions(-) diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 6ef7b89918..74d53ee3f6 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -115,7 +115,7 @@ Build a docs site quickly by importing your existing styling and specs. **Q: How do I get started with Fern Docs?** -Install the Fern CLI with `npm install -g fern-api`, then run `fern init` in your project directory. This creates a `fern/` folder with a starter `docs.yml` and example pages. Run `fern docs dev` to preview locally, and `fern docs generate` to publish to your Fern subdomain. +Install the Fern CLI with `npm install -g fern-api`, then run `fern init` in your project directory. This creates a `fern/` folder with a minimal scaffold. Run `fern docs dev` to preview locally, and `fern generate --docs` to publish to your Fern subdomain. **Q: What can I build with Fern Docs?** @@ -127,10 +127,10 @@ Yes. You can define multiple versions in `docs.yml` using the `versions` key. Ea **Q: Can I use Fern Docs with GitLab?** -Fern Docs connects to GitHub repositories for automated deployments via the Fern GitHub App. GitLab is not currently supported for the automated git-connected deployment workflow, but you can publish manually using the Fern CLI and a CI/CD pipeline in GitLab with `fern docs generate`. +Fern Docs connects to GitHub repositories for automated deployments via the Fern GitHub App. GitLab is not currently supported for the automated git-connected deployment workflow, but you can publish manually using the Fern CLI and a CI/CD pipeline in GitLab with `fern generate --docs`. **Q: How do I add a changelog to my Fern docs site?** -Create a `changelog/` directory inside your `fern/pages/` folder and add `.mdx` files named by date (e.g., `2024-01-15.mdx`). Register the changelog in `docs.yml` under your navigation using `changelog: ./pages/changelog`. Each file becomes a dated changelog entry. +Create a `changelog/` folder directly inside your `fern/` folder (not inside `pages/`). Name each entry file by date using one of these formats: `YYYY-MM-DD.md`, `MM-DD-YYYY.md`, or `MM-DD-YY.md`. Register it in `docs.yml` either as a tab (using `changelog: ./changelog` under the tab definition) or as a section-level entry (`- changelog: ./changelog`). Subdirectories within the `changelog` folder are not supported. - + \ No newline at end of file diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index aad3141b5d..5972456e65 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -414,17 +414,17 @@ This is enough to publish (the CLI will build an empty site). In practice, most ## Frequently Asked Questions -**Q: What is the `fern docs generate` command?** +**Q: What is the `fern generate --docs` command?** -`fern docs generate` builds and publishes your documentation to your configured Fern docs instance. It validates your `docs.yml`, compiles your MDX pages and API definitions, and deploys to your subdomain (e.g., `yourorg.docs.buildwithfern.com`) or custom domain. Run it from the root of your repository where the `fern/` folder lives. +`fern generate --docs` builds and publishes your documentation to your configured Fern docs instance. It validates your `docs.yml`, compiles your MDX pages and API definitions, and deploys to your subdomain (e.g., `yourorg.docs.buildwithfern.com`) or custom domain. Run it from the root of your repository where the `fern/` folder lives. To target a specific instance when you have multiple configured, use `fern generate --docs --instance yourorg.docs.buildwithfern.com`. **Q: How do I publish docs to a custom domain?** In `docs.yml`, set the `custom-domain` field under your instance URL. Then add a CNAME DNS record pointing your domain to `fern.buildwithfern.com`. Custom domains are available on paid plans. -**Q: Why does `fern docs generate` say "No docs instance found"?** +**Q: Why does `fern generate --docs` say "No docs instance found"?** -This error means the `--instance` flag value doesn't exactly match the URL configured in `docs.yml`. The instance URL in `docs.yml` must match the value you pass to `--instance` without the `https://` prefix. For example, if `docs.yml` has `url: myorg.docs.buildwithfern.com`, run `fern docs generate --instance myorg.docs.buildwithfern.com`. +This error means the `--instance` flag value doesn't exactly match the URL configured in `docs.yml`. The instance URL in `docs.yml` must include the `https://` prefix, but the `--instance` flag value must not. For example, if `docs.yml` has `url: myorg.docs.buildwithfern.com`, run `fern generate --docs --instance myorg.docs.buildwithfern.com`. **Q: How do I preview my docs locally before publishing?** @@ -432,6 +432,6 @@ Run `fern docs dev` to start a local preview server. This hot-reloads as you edi **Q: How do I set up a GitHub Action to auto-publish my docs?** -Create a workflow file at `.github/workflows/publish-docs.yml`. On push to your main branch, run `fern docs generate` with `FERN_TOKEN` set as a GitHub Actions secret. The Fern GitHub App can also trigger deployments automatically when connected to your repository from the Fern dashboard. +Create a workflow file at `.github/workflows/publish-docs.yml`. On push to your main branch, run `fern generate --docs` with `FERN_TOKEN` set as a GitHub Actions secret. - + \ No newline at end of file diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index cb05e54efb..2a7b5e39d3 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1354,7 +1354,7 @@ Navigation is defined in `docs.yml` under the `navigation` key (or per-product/t **Q: How do I add tabs to my Fern docs site?** -Add a `tabs` key to your `docs.yml` with each tab's display name and path. Each tab can have its own navigation tree. Tabs appear in the header or sidebar depending on your `layout.tabs-placement` setting (`header` or `sidebar`). +Tabs are configured in two places in `docs.yml`. First, declare each tab under the top-level `tabs` key with a `display-name` and optional `icon`. Then reference each tab in the `navigation` section using `tab:`. Each tab requires either a `layout` for its content or an `href` for an external link. Tabs appear in the sidebar by default. To control placement and style, use the `theme.tabs` key: set `placement` to `header` or `sidebar`, `style` to `default` (underline) or `bubble` (pill), and `alignment` to `left` or `center` (center only applies to header tabs). **Q: How do I set a custom favicon and logo?** @@ -1362,10 +1362,10 @@ In `docs.yml`, set `favicon` to the path of your `.png` or `.ico` file, and set **Q: How do I change the accent color of my docs site?** -In `docs.yml`, set `colors.accent-primary.light` and `colors.accent-primary.dark` to your desired hex color values. You can also set `colors.background`, `colors.border`, `colors.header-background`, and `colors.card-background` for full theme control. +In `docs.yml`, set `colors.accent-primary.light` and `colors.accent-primary.dark` to your desired hex color values. You can also set `colors.background`, `colors.border`, `colors.header-background`, `colors.sidebar-background`, and `colors.card-background` for full theme control. **Q: How do I add custom CSS or JavaScript to my Fern docs?** Set `css: ./assets/styles.css` in `docs.yml` to inject a custom stylesheet. For JavaScript, use the `js` key with a path and optional `strategy` (`beforeInteractive`, `afterInteractive`, or `lazyOnload`). - + \ No newline at end of file diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 662715e64c..17b6008d92 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -299,7 +299,7 @@ Fern generates SDKs in TypeScript/JavaScript, Python, Java, Go, C#/.NET, Ruby, P **Q: How do I generate a TypeScript SDK with Fern?** -Add the TypeScript generator to your `generators.yml` file under the `sdks` group: `- name: fernapi/fern-typescript-node-sdk`. Then run `fern generate` to produce the SDK. To publish to npm, configure the `npm` key with your package name and set `FERN_TOKEN` and `NPM_TOKEN` as environment variables in your CI pipeline. +Add the TypeScript generator to your `generators.yml` file under the `sdks` group: `- name: fernapi/fern-typescript-node-sdk`. Then run `fern generate` to produce the SDK. To publish to npm, configure the `npm` key with your package name and set `NPM_TOKEN` as an environment variable in your CI pipeline. **Q: How do I generate a Python SDK with Fern?** @@ -307,7 +307,7 @@ Add `- name: fernapi/fern-python-sdk` to your `generators.yml`. Run `fern genera **Q: Does Fern support SDK versioning?** -Yes. Fern SDKs are versioned via your package manager (npm, PyPI, Maven, etc.). When you run `fern generate` with publishing configured, Fern tags and publishes a new version. You control the version number in `generators.yml` under the `version` key, or by passing `--version` to the CLI. +Fern SDKs are versioned via your package manager (npm, PyPI, Maven, etc.). In cloud generation, Fern manages versioning for you. In self-hosted setups, you pass the version via CLI flag: `--version` (CLI v1) or `--output-version` (CLI v2). Fern also provides two automated workflows for computing the next version: `--version AUTO` (AI-powered, Enterprise) and `fern ir` + `fern diff` (deterministic). **Q: How do I deprecate an endpoint in my Fern SDK?** @@ -315,6 +315,11 @@ In OpenAPI, add `deprecated: true` to the operation. Fern will mark the correspo **Q: Does Fern support retries in generated SDKs?** -Yes. Fern SDKs include built-in retry logic with exponential backoff by default. You can configure the number of retries at the client level. To disable retries for a specific endpoint, use the `x-fern-retries: { disabled: true }` OpenAPI extension on that operation. +Yes. Fern SDKs include built-in retry logic with exponential backoff by default. You can configure the number of retries at the client level. To disable retries for a specific endpoint, add the `x-fern-retries` OpenAPI extension to that operation: - +```yaml +x-fern-retries: + disabled: true +``` + + \ No newline at end of file From db1b61d1c090be3e142af36b8213d4b54bc2b6aa Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:53:50 +0000 Subject: [PATCH 4/5] Correct changelog setup answer in capabilities llms-only FAQ --- fern/products/docs/pages/getting-started/capabilities.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 74d53ee3f6..29592f3daf 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -131,6 +131,6 @@ Fern Docs connects to GitHub repositories for automated deployments via the Fern **Q: How do I add a changelog to my Fern docs site?** -Create a `changelog/` folder directly inside your `fern/` folder (not inside `pages/`). Name each entry file by date using one of these formats: `YYYY-MM-DD.md`, `MM-DD-YYYY.md`, or `MM-DD-YY.md`. Register it in `docs.yml` either as a tab (using `changelog: ./changelog` under the tab definition) or as a section-level entry (`- changelog: ./changelog`). Subdirectories within the `changelog` folder are not supported. +Create a folder named exactly `changelog` anywhere inside your `fern/` directory — for example, `fern/changelog/` or `fern/pages/changelog/`. Name each entry file by date using one of these formats: `YYYY-MM-DD`, `MM-DD-YYYY`, or `MM-DD-YY`. Both `.md` and `.mdx` are supported. Subdirectories within the `changelog` folder are not supported. Register it in `docs.yml` by pointing the `changelog` key at the folder path, either as a tab (e.g., `changelog: ./changelog`) or as a section-level entry (e.g., `- changelog: ./changelog`). The path is relative to the `docs.yml` file where it is set. \ No newline at end of file From 3da853981a795d3c78f69ccffb9fa63cfd6fefbb Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Wed, 26 Aug 2026 21:09:19 +0000 Subject: [PATCH 5/5] Fix llms-only FAQ accuracy Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/ai/mcp-server.mdx | 14 +++++++------- .../docs/pages/getting-started/capabilities.mdx | 12 ++++++------ .../docs/pages/getting-started/quickstart.mdx | 14 +++++--------- .../docs/pages/navigation/site-level-settings.mdx | 10 +++++----- fern/products/sdks/introduction.mdx | 12 ++++++------ 5 files changed, 29 insertions(+), 33 deletions(-) diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 7e336b49a6..b79f01ef64 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -106,15 +106,15 @@ Agents can also fetch documentation directly over HTTP. Fern serves clean Markdo -## Frequently Asked Questions +## Frequently asked questions **Q: What are the two different MCP servers in Fern, and which one is this page about?** There are two distinct MCP servers in the Fern ecosystem: -1. **Your docs site's MCP server** (this page): Fern automatically generates and hosts an MCP server for *your* documentation site at `your-documentation-site.com/_mcp/server`. This is what your *readers and their AI coding agents* connect to in order to query your product's documentation. It is enabled automatically on any Fern docs site with Ask Fern turned on. +1. **Your docs site's MCP server** (this page): Fern automatically generates and hosts an MCP server for *your* documentation site at `your-documentation-site.com/_mcp/server`. This is what your *readers and their AI coding agents* connect to query your product's documentation. It's enabled automatically on any Fern docs site with Ask Fern turned on. -2. **Fern's own MCP server** (for building with Fern): A separate MCP server that points at Fern's own product documentation and tooling. This is what *you* connect to when you want your AI coding agent (Claude Code, Cursor, Windsurf, etc.) to help you author, configure, or edit your Fern docs site. It is documented at https://buildwithfern.com/learn/docs/ai-features/agent-setup. +2. **Fern's own MCP server** (for building with Fern): A separate MCP server that points at Fern's own product documentation and tooling. This is what *you* connect to when you want your AI coding agent (Claude Code, Cursor, Windsurf, etc.) to help you author, configure, or edit your Fern docs site. It's documented on [Fern's MCP server page](/learn/docs/ai-features/fern-mcp-servers), with [agent setup instructions](/learn/docs/ai-features/agent-setup) as a secondary reference. If you are trying to help your users query your API documentation from their coding agent, you want **this page**. If you are trying to set up an AI agent to help you work on your own Fern docs site, see the Fern Agent setup page instead. @@ -130,14 +130,14 @@ For Claude Code and Cursor, Fern adds one-click connection buttons to your docs **Q: Is my docs site's MCP server enabled by default?** -Yes, it is enabled automatically on any Fern docs site with Ask Fern enabled. No configuration is required. To disable it, set `mcp: false` under `page-actions.options` in `docs.yml`. +Yes, it's enabled automatically on any Fern docs site with Ask Fern enabled. No configuration is required. To disable it, set `mcp: false` under `page-actions.options` in `docs.yml`. **Q: Does the MCP server work on authenticated (private) docs sites?** -Yes, but MCP clients must include a `FERN_TOKEN` header containing a valid JWT. Without it, the server only returns publicly visible content. Readers exchange their credentials for a JWT via the `/api/fern-docs/get-jwt` endpoint, then add the token as a header in their MCP client configuration. +Yes, but MCP clients must include a `FERN_TOKEN` header containing a valid JWT. Without it, the server only returns publicly visible content. For API-key, JWT, and OAuth sites, readers exchange their credentials for a JWT via `/api/fern-docs/get-jwt`. Password-protected sites use `/api/fern-docs/auth/password`. Add the resulting token as a header in the MCP client configuration. **Q: How do I set up an AI agent to help me build or edit my Fern docs site?** -That uses Fern's own MCP server, not your docs site's MCP server. See https://buildwithfern.com/learn/docs/ai-features/agent-setup for setup instructions. You connect your coding agent to Fern's MCP server, which gives it access to Fern's product documentation and editing capabilities. +That uses Fern's own MCP server, not your docs site's MCP server. See [Fern's MCP server page](/learn/docs/ai-features/fern-mcp-servers), with [agent setup instructions](/learn/docs/ai-features/agent-setup) as a secondary reference. You connect your coding agent to Fern's MCP server, which gives it access to Fern's product documentation and editing capabilities. - \ No newline at end of file + diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 29592f3daf..75e54db2e9 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -111,7 +111,7 @@ Build a docs site quickly by importing your existing styling and specs. -## Frequently Asked Questions +## Frequently asked questions **Q: How do I get started with Fern Docs?** @@ -119,18 +119,18 @@ Install the Fern CLI with `npm install -g fern-api`, then run `fern init` in you **Q: What can I build with Fern Docs?** -Fern Docs lets you build interactive API reference documentation, markdown-based guides, changelogs, versioned docs, and multi-product documentation sites. It supports custom domains, theming, search, AI-powered Ask Fern chat, MCP server integration, and llms.txt for AI agent discoverability. +Fern Docs lets you build interactive API Reference documentation, markdown-based guides, changelogs, versioned docs, and multi-product documentation sites. It supports custom domains, theming, search, AI-powered Ask Fern chat, MCP server integration, and llms.txt for AI agent discoverability. **Q: Does Fern Docs support versioning?** -Yes. You can define multiple versions in `docs.yml` using the `versions` key. Each version points to its own navigation configuration. Readers can switch between versions using a dropdown in the docs header. +Yes. Versioning is a Team plan feature. Define multiple versions in `docs.yml` using the `versions` key, with each version represented by a `.yml` file in a `fern/versions/` folder. Readers can switch between versions using a dropdown in the docs header. **Q: Can I use Fern Docs with GitLab?** -Fern Docs connects to GitHub repositories for automated deployments via the Fern GitHub App. GitLab is not currently supported for the automated git-connected deployment workflow, but you can publish manually using the Fern CLI and a CI/CD pipeline in GitLab with `fern generate --docs`. +Yes. [GitLab CI/CD](/learn/docs/developer-tools/git-lab) can generate preview links on merge requests and publish your docs when changes are merged to `main`. The Fern Agent editing workflow is GitHub-only. **Q: How do I add a changelog to my Fern docs site?** -Create a folder named exactly `changelog` anywhere inside your `fern/` directory — for example, `fern/changelog/` or `fern/pages/changelog/`. Name each entry file by date using one of these formats: `YYYY-MM-DD`, `MM-DD-YYYY`, or `MM-DD-YY`. Both `.md` and `.mdx` are supported. Subdirectories within the `changelog` folder are not supported. Register it in `docs.yml` by pointing the `changelog` key at the folder path, either as a tab (e.g., `changelog: ./changelog`) or as a section-level entry (e.g., `- changelog: ./changelog`). The path is relative to the `docs.yml` file where it is set. +Create a folder named exactly `changelog` anywhere inside your `fern/` directory — for example, `fern/changelog/` or `fern/pages/changelog/`. Name each entry file by date using one of these formats: `YYYY-MM-DD`, `MM-DD-YYYY`, or `MM-DD-YY`. Both `.md` and `.mdx` are supported. Subdirectories within the `changelog` folder aren't supported. Register it in `docs.yml` by pointing the `changelog` key at the folder path, either as a tab (e.g., `changelog: ./changelog`) or as a section-level entry (e.g., `- changelog: ./changelog`). The path is relative to the `docs.yml` file where it's set. - \ No newline at end of file + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index 5972456e65..790d0c0120 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -412,26 +412,22 @@ This is enough to publish (the CLI will build an empty site). In practice, most -## Frequently Asked Questions +## Frequently asked questions -**Q: What is the `fern generate --docs` command?** +**Q: What's the `fern generate --docs` command?** `fern generate --docs` builds and publishes your documentation to your configured Fern docs instance. It validates your `docs.yml`, compiles your MDX pages and API definitions, and deploys to your subdomain (e.g., `yourorg.docs.buildwithfern.com`) or custom domain. Run it from the root of your repository where the `fern/` folder lives. To target a specific instance when you have multiple configured, use `fern generate --docs --instance yourorg.docs.buildwithfern.com`. **Q: How do I publish docs to a custom domain?** -In `docs.yml`, set the `custom-domain` field under your instance URL. Then add a CNAME DNS record pointing your domain to `fern.buildwithfern.com`. Custom domains are available on paid plans. - -**Q: Why does `fern generate --docs` say "No docs instance found"?** - -This error means the `--instance` flag value doesn't exactly match the URL configured in `docs.yml`. The instance URL in `docs.yml` must include the `https://` prefix, but the `--instance` flag value must not. For example, if `docs.yml` has `url: myorg.docs.buildwithfern.com`, run `fern generate --docs --instance myorg.docs.buildwithfern.com`. +Fern recommends using the [Fern Dashboard](/learn/dashboard/configuration/custom-domains) to set up custom domains because it provides the correct DNS records for your domain. For manual setup, add `custom-domain` under the instance in `docs.yml`, then contact Fern for a unique per-site CNAME value and a TXT verification record. **Q: How do I preview my docs locally before publishing?** -Run `fern docs dev` to start a local preview server. This hot-reloads as you edit your MDX pages and `docs.yml`. The local preview is available at `http://localhost:3000` by default. +Run `fern docs dev` to start a local preview server. This hot-reloads as you edit MDX pages and `docs.yml`. pnpm must be available on `PATH`. The local preview uses port 3000 by default; pass `--port` to override it. If port 3000 is already in use, Fern uses the next available port. **Q: How do I set up a GitHub Action to auto-publish my docs?** Create a workflow file at `.github/workflows/publish-docs.yml`. On push to your main branch, run `fern generate --docs` with `FERN_TOKEN` set as a GitHub Actions secret. - \ No newline at end of file + diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 2a7b5e39d3..2ef4c3d035 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1346,11 +1346,11 @@ experimental: -## Frequently Asked Questions +## Frequently asked questions **Q: How do I configure the navigation in my Fern docs?** -Navigation is defined in `docs.yml` under the `navigation` key (or per-product/tab config files). You can nest sections, pages, API references, and links. Use `section` for collapsible groups, `page` for MDX files, and `api` for API reference sections generated from your OpenAPI or Fern definition. +Navigation is defined in `docs.yml` under the `navigation` key (or per-product/tab config files). You can nest sections, pages, API references, and links. Use `section` for collapsible groups, `page` for MDX files, and `api` for API Reference sections generated from your OpenAPI or Fern definition. **Q: How do I add tabs to my Fern docs site?** @@ -1358,7 +1358,7 @@ Tabs are configured in two places in `docs.yml`. First, declare each tab under t **Q: How do I set a custom favicon and logo?** -In `docs.yml`, set `favicon` to the path of your `.png` or `.ico` file, and set `logo.light` and `logo.dark` to your SVG or PNG logo paths. All paths are relative to the `fern/` folder. +In `docs.yml`, set `favicon` to the favicon path, and set `logo.light` and `logo.dark` to the logo paths. Paths are relative to the YAML file where they're set, such as `docs.yml`. **Q: How do I change the accent color of my docs site?** @@ -1366,6 +1366,6 @@ In `docs.yml`, set `colors.accent-primary.light` and `colors.accent-primary.dark **Q: How do I add custom CSS or JavaScript to my Fern docs?** -Set `css: ./assets/styles.css` in `docs.yml` to inject a custom stylesheet. For JavaScript, use the `js` key with a path and optional `strategy` (`beforeInteractive`, `afterInteractive`, or `lazyOnload`). +Set `css: ./assets/styles.css` in `docs.yml` to inject a custom stylesheet. For JavaScript, use the `js` key with a path and optional `strategy` (`beforeInteractive`, `afterInteractive`, or `lazyOnload`). `strategy` applies to local scripts in the list form with `path:`. - \ No newline at end of file + diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 17b6008d92..061075c674 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -291,19 +291,19 @@ Generate client libraries in multiple languages from your API definition. -## Frequently Asked Questions +## Frequently asked questions **Q: What languages does Fern support for SDK generation?** -Fern generates SDKs in TypeScript/JavaScript, Python, Java, Go, C#/.NET, Ruby, PHP, and Swift. Each language has its own generator configured in `generators.yml`. +Fern generates SDKs in TypeScript/JavaScript, Python, Java, Go, C#/.NET, Ruby, PHP, Swift, and Rust. Each language has its own generator configured in `generators.yml`. **Q: How do I generate a TypeScript SDK with Fern?** -Add the TypeScript generator to your `generators.yml` file under the `sdks` group: `- name: fernapi/fern-typescript-node-sdk`. Then run `fern generate` to produce the SDK. To publish to npm, configure the `npm` key with your package name and set `NPM_TOKEN` as an environment variable in your CI pipeline. +Run `fern add fern-typescript-sdk --group ts-sdk` to add the TypeScript generator to `generators.yml`. The group name is user-chosen; `ts-sdk` is an example. This adds the `fern-typescript-sdk` generator. Then run `fern generate --group ts-sdk` to produce the SDK. To publish to npm, configure `output` with `location: npm`, `package-name`, and `token: ${NPM_TOKEN}`. **Q: How do I generate a Python SDK with Fern?** -Add `- name: fernapi/fern-python-sdk` to your `generators.yml`. Run `fern generate` to produce the SDK. To publish to PyPI, configure the `pypi` key with your package name and set `FERN_TOKEN` and `PYPI_TOKEN` in your CI environment. +Run `fern add fern-python-sdk --group python-sdk` to add the Python generator to `generators.yml`. The group name is user-chosen; `python-sdk` is an example. This adds the `fern-python-sdk` generator. Then run `fern generate --group python-sdk` to produce the SDK. To publish to PyPI, configure `output` with `location: pypi`, `package-name`, and `token: ${PYPI_TOKEN}`. **Q: Does Fern support SDK versioning?** @@ -311,7 +311,7 @@ Fern SDKs are versioned via your package manager (npm, PyPI, Maven, etc.). In cl **Q: How do I deprecate an endpoint in my Fern SDK?** -In OpenAPI, add `deprecated: true` to the operation. Fern will mark the corresponding SDK method as deprecated in the generated code (e.g., `@deprecated` in TypeScript/Java, deprecation warnings in Python). You can also use the `x-fern-availability` extension with value `deprecated` for more granular control. +In OpenAPI, add `deprecated: true` to the operation. You can also use the `x-fern-availability` extension with value `deprecated` for more granular control. **Q: Does Fern support retries in generated SDKs?** @@ -322,4 +322,4 @@ x-fern-retries: disabled: true ``` - \ No newline at end of file +