diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index f9e516711a..b79f01ef64 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -104,3 +104,40 @@ 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 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 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'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. + +--- + +**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?** + +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. 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 [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. + + diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 947c4a70dd..75e54db2e9 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 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?** + +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. 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?** + +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 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. + + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index fb60a7a8fd..790d0c0120 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -409,3 +409,25 @@ 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'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?** + +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 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. + + diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 7869127e8d..2ef4c3d035 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?** + +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?** + +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?** + +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`). `strategy` applies to local scripts in the list form with `path:`. + + diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 57ca62637b..061075c674 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -288,3 +288,38 @@ 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, Swift, and Rust. Each language has its own generator configured in `generators.yml`. + +**Q: How do I generate a TypeScript SDK with Fern?** + +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?** + +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?** + +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?** + +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?** + +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 +``` + +