diff --git a/fern/products/api-def/openapi/overview.mdx b/fern/products/api-def/openapi/overview.mdx index 7632d02cae..2496f9165b 100644 --- a/fern/products/api-def/openapi/overview.mdx +++ b/fern/products/api-def/openapi/overview.mdx @@ -167,3 +167,34 @@ This will initialize a directory like the following: + + +## Frequently Asked Questions + +**Q: How do I use an OpenAPI spec with Fern?** +A: Run `fern init --openapi ./path/to/openapi` (a local file or a URL) to create a `fern` folder that references your spec, then generate docs with `fern generate --docs` or SDKs with `fern generate`. + +**Q: Does Fern support OpenAPI 3.0 and 3.1?** +A: Yes. Fern is compatible with the latest OpenAPI release (currently v3.1.1) and reads specs written in earlier 3.x versions, in either YAML or JSON. + +**Q: What Fern-specific OpenAPI extensions are available?** +A: `x-fern-*` extensions customize generation without changing the meaning of your API: SDK group and method names, availability, audiences, base paths, default values, enum names, examples, global headers and parameters, idempotency, pagination, parameter and property names, retries, schema names, and server names. See the [extensions overview](/learn/api-definitions/openapi/extensions/overview). + +**Q: How do I use `x-fern-sdk-group-name` and `x-fern-sdk-method-name`?** +A: Add them to an operation to control where it lands in the generated SDK: the group becomes the sub-client (`client.users.create(...)`) and the method name becomes the function. Multiple group names nest sub-clients. See [SDK method names](/learn/api-definitions/openapi/extensions/method-names). + +**Q: How do I deprecate an endpoint in OpenAPI with Fern?** +A: Set `x-fern-availability: deprecated` on the operation. The API Reference shows a `Deprecated` tag, and the TypeScript generator marks the client method `@deprecated`. See [Availability](/learn/api-definitions/openapi/extensions/availability). + +**Q: Does Fern support PATCH, PUT, DELETE, and other HTTP methods?** +A: Yes. Fern reads the standard OpenAPI operations for a path, so every HTTP method your spec declares is documented and generated. + +**Q: How do I configure retries with `x-fern-retries`?** +A: Add `x-fern-retries: { disabled: true }` to an operation to turn retries off for it in every SDK language, overriding user-level retry settings. Use it for non-idempotent operations such as payments or order creation. See [Retry behavior](/learn/api-definitions/openapi/extensions/retry-behavior). + +**Q: Can I use an OpenAPI overlay with Fern?** +A: Yes, and it's the recommended way to customize: keep your core spec untouched and put Fern extensions in an [overlay file](/learn/api-definitions/openapi/overlays). + +**Q: What should I fix in my spec before generating?** +A: Give every endpoint a clear `operationId`, define reusable schemas under `components/schemas` and reference them with `$ref` rather than inlining, and keep customizations in overlays. + diff --git a/fern/products/cli-api-reference/pages/cli-get-started.mdx b/fern/products/cli-api-reference/pages/cli-get-started.mdx index 3dd301e15d..0844ec16b4 100644 --- a/fern/products/cli-api-reference/pages/cli-get-started.mdx +++ b/fern/products/cli-api-reference/pages/cli-get-started.mdx @@ -109,3 +109,32 @@ The [general](/learn/cli-api-reference/cli-reference/general-commands), [docs](/ + + + +## Frequently Asked Questions + +**Q: What are the main Fern CLI commands?** +A: `fern init` creates a project, `fern check` validates it, `fern docs dev` previews docs locally, `fern generate --docs` publishes docs, and `fern generate` builds and publishes SDKs. The [general](/learn/cli-api-reference/cli-reference/general-commands), [docs](/learn/cli-api-reference/cli-reference/docs-commands), and [SDK](/learn/cli-api-reference/cli-reference/sdk-commands) references document every command and flag. + +**Q: How do I install the Fern CLI?** +A: `npm install -g fern-api` (Node.js 22 or higher) or `brew install fern-api` on macOS and Linux. Verify with `fern -v`. + +**Q: Can I install Fern per project instead of globally?** +A: Yes. Run `npm install fern-api`, set `"version": "*"` in `fern.config.json`, and invoke commands through npm (`npm fern check`). Homebrew supports system-wide installs only. + +**Q: What does `fern generate` do?** +A: It runs SDK generation for the generator groups in `generators.yml`. Add `--group ` for one group, `--preview` to generate into a local `.preview/` folder, and `--local` to generate on your own machine. + +**Q: How do I use `fern generate --docs` versus `fern generate`?** +A: `--docs` builds and publishes your documentation site; without it, the command builds and publishes SDKs. They read the same project but different configuration: `docs.yml` for docs, `generators.yml` groups for SDKs. + +**Q: What does `fern check` do?** +A: It validates your API definition and configuration — `fern.config.json`, `generators.yml`, and `docs.yml` — including broken internal links and API examples. It prints nothing when everything passes. + +**Q: What's `fern init` and when do I use it?** +A: Use it once per project to create the `fern` folder. `fern init --openapi ` starts from an existing spec, `fern init --docs` adds a sample docs site, and `--mintlify` or `--readme` import an existing docs site. + +**Q: How do I upgrade the Fern CLI?** +A: `fern upgrade` bumps the version in `fern.config.json` and moves generators to their minimum-compatible versions; `fern upgrade --version ` targets a specific release, and `fern downgrade ` moves back. Upgrading the npm or Homebrew package updates the binary itself. + diff --git a/fern/products/cli-api-reference/pages/docs-commands.mdx b/fern/products/cli-api-reference/pages/docs-commands.mdx index a8fb195307..0499d066f8 100644 --- a/fern/products/cli-api-reference/pages/docs-commands.mdx +++ b/fern/products/cli-api-reference/pages/docs-commands.mdx @@ -427,3 +427,29 @@ These commands build, preview, and publish a Fern documentation site, and valida + + + +## Frequently Asked Questions + +**Q: What's the `fern generate --docs` command?** +A: It builds your documentation site and publishes it to the instance URL configured in `docs.yml`. Use `--instance` to choose among multiple instances, `--preview` for a temporary preview deployment, `--id` for a stable preview name, and `--force` to skip the overwrite confirmation in CI. + +**Q: How do I preview my docs locally before publishing?** +A: `fern docs dev` runs a local development server with hot reloading; pass `--port` to choose the port. On Windows it requires long path support enabled, or WSL. + +**Q: How do I share a preview with my team?** +A: `fern generate --docs --preview` publishes a preview deployment and prints its URL. Adding `--preview --id my-feature` gives a stable `{org}-preview-{id}.docs.buildwithfern.com` link that updates in place — useful for one preview per pull request. + +**Q: How do I manage existing previews?** +A: `fern docs preview list` shows preview deployments and `fern docs preview delete` removes one. + +**Q: How do I check for broken links?** +A: `fern docs link check` checks links, including external ones, on a live published site. To validate internal links before publishing, use the `broken-links` rule run by `fern check`. + +**Q: How do I validate my MDX?** +A: `fern docs md check` validates MDX syntax across your documentation files. + +**Q: How do I connect a coding agent to Fern over MCP?** +A: `fern mcp install` registers Fern's MCP server with your supported clients; `--client` targets specific ones and `--org` overrides the organization from `fern.config.json`. + diff --git a/fern/products/cli-api-reference/pages/general-commands.mdx b/fern/products/cli-api-reference/pages/general-commands.mdx index 27fabe6170..e5aaade4ef 100644 --- a/fern/products/cli-api-reference/pages/general-commands.mdx +++ b/fern/products/cli-api-reference/pages/general-commands.mdx @@ -493,3 +493,32 @@ These commands apply to every Fern project, whether it publishes [docs](/learn/c + + + +## Frequently Asked Questions + +**Q: What does `fern check` do?** +A: It validates your API definition and Fern configuration — `fern.config.json`, `generators.yml`, and `docs.yml` — reporting broken internal links, invalid examples, and configuration errors. Successful runs print nothing. Set each rule to `warn` or `error` under `check.rules` in `docs.yml`. + +**Q: Does `fern check` check my live site?** +A: No. Its rules validate the navigation tree built from your local configuration and don't crawl your deployed site or follow external URLs. The exception is `missing-redirects`, which compares against the last published state and needs `fern login` or `FERN_TOKEN`. For a published site, use `fern docs link check`. + +**Q: How do I upgrade the Fern CLI?** +A: `fern upgrade` sets `fern.config.json` to the latest allowed version and moves generators to their minimum-compatible versions. Use `--version` for a specific release, `--from` when version inference is wrong, and `--yes` in non-interactive environments. If your organization has a CLI version policy, the highest version the policy allows wins. + +**Q: What's `fern init` and when do I use it?** +A: Run it once to create a `fern` workspace. `--openapi ` scaffolds around an existing spec, `--docs` adds a sample docs site, and `--mintlify` or `--readme` convert an existing docs site into a Fern project. + +**Q: How do I authenticate the CLI?** +A: `fern login` opens a browser for GitHub, Google, or Postman; `--device-code` covers environments without a browser, and `--email` uses enterprise SSO. For CI, generate an organization-scoped key with `fern token` and set it as `FERN_TOKEN`. + +**Q: How do I get an OpenAPI spec out of Fern?** +A: `fern export path/to/openapi.yml` writes a spec for your API, which is useful when your API is defined in the Fern Definition. The extension (`.yml` or `.json`) chooses the output format. + +**Q: How do I pull the latest version of my spec?** +A: `fern api update` fetches the spec from the `origin` configured in `generators.yml` and updates the local copy. The same step can run on a schedule in a GitHub Action. + +**Q: Can I pin one CLI version for my whole organization?** +A: Yes. An organization admin sets a minimum, maximum, or exact version with `fern org set cli-version`, inspects it with `fern org get`, and clears it with `fern org unset cli-version`. + diff --git a/fern/products/cli-api-reference/pages/sdk-commands.mdx b/fern/products/cli-api-reference/pages/sdk-commands.mdx index 0660f09d1a..bc41bf9a66 100644 --- a/fern/products/cli-api-reference/pages/sdk-commands.mdx +++ b/fern/products/cli-api-reference/pages/sdk-commands.mdx @@ -378,4 +378,33 @@ These commands generate SDKs from your API definition, keep generators up to dat ``` - \ No newline at end of file + + + + +## Frequently Asked Questions + +**Q: What does `fern generate` do?** +A: It runs the Fern compiler to produce SDKs for the generator groups in `generators.yml`, then publishes or saves each one to its configured output. Remote generation (the default) requires `fern login` or `FERN_TOKEN`; `--local` doesn't. + +**Q: How do I generate only one SDK?** +A: `fern generate --group `, using a group name or an alias defined in `generators.yml`. In multi-API projects, add `--api ` matching the folder in `fern/apis/`. + +**Q: How do I preview an SDK locally before publishing?** +A: `fern generate --preview` writes the SDK to a local `.preview/` folder and publishes nothing to GitHub or a package registry. + +**Q: How do I generate SDKs on my own machine?** +A: `fern generate --local` runs generation in Docker on your infrastructure, so a Docker daemon must be running. It requires no login and isn't rate limited. + +**Q: How do I set the SDK version?** +A: `fern generate --version `, typically from a CI/CD release workflow. Combine it with `--group` and `--api` to version a single SDK. + +**Q: How do I run generation in CI without prompts?** +A: Set `FERN_TOKEN` and pass `--force` to skip confirmation prompts. + +**Q: How do I build a distributable package without publishing to a registry?** +A: `fern generate --package` builds an artifact (npm tarball, wheel, JAR, NuGet package, gem, Composer archive, crate, or Go source zip) into a `fern-dist/` folder for every `local-file-system` output. `--package-mode docker` runs the toolchains in containers, and `--package-only` keeps just the artifact. + +**Q: What are the Replay commands for?** +A: `fern replay resolve` walks through conflicts left when the generator and your customizations touched the same lines, and `fern replay forget` removes tracked patches from `.fern/replay.lock`. `fern generate --no-replay` skips patch application for one local run. + diff --git a/fern/products/docs/pages/ai/fern-agent.mdx b/fern/products/docs/pages/ai/fern-agent.mdx index 83a72e6207..cb6722c862 100644 --- a/fern/products/docs/pages/ai/fern-agent.mdx +++ b/fern/products/docs/pages/ai/fern-agent.mdx @@ -200,3 +200,29 @@ What Fern Agent adds is context on your organization and more places to work fro Fern Agent acts with your own Fern permissions on every surface, so it reads and edits only the sites, analytics, and organization data your account can already see. Requests are scoped to a single session: the prompt, any Slack message or thread you tag it in, and attached files are stored to complete the task and aren't retained afterward. Editing is powered by [Devin from Cognition](https://cognition.ai/blog/introducing-devin). Neither Fern nor [Devin](https://docs.devin.ai/admin/security#how-is-your-data-used-to-improve-devin) uses your data to train AI models: Fern configures its Devin integration to opt out of any data collection for model training, so your messages, code, and documentation content are never used for training. + + + +## Frequently Asked Questions + +**Q: What's Fern Writer and how does it relate to Fern Agent?** +A: Fern Agent is an expansion of Fern Writer. Fern Writer opened documentation pull requests from Slack and still does — existing installations keep working and the request flow is unchanged. Fern Agent adds organization context (traffic, reader questions, deployments, configuration) and two more surfaces: the Fern Dashboard and your coding agent over MCP. + +**Q: What can Fern Agent do?** +A: Edit your docs (copy, navigation, versions, redirects, components, authentication), query analytics such as pageviews, 404s, referrers, search queries and reader feedback, summarize Ask Fern conversations and resolution rates, and report deployment history and site configuration. Organization administration stays read-only. + +**Q: How do I use Fern Agent to generate documentation?** +A: Describe the change in the Dashboard chat panel, in a Slack channel where `@Fern` has been added, or through your coding agent over MCP. It reads your docs repository, makes the change, and delivers it as a pull request — or iterates live in the [visual editor](/learn/docs/writing-content/fern-editor). + +**Q: Can Fern Agent update existing documentation pages?** +A: Yes. It edits existing pages and configuration as well as adding new ones, and it writes the accompanying Fern configuration — a moved page gets its redirect, a new page gets its navigation entry. + +**Q: Does Fern Agent work with the visual editor?** +A: Yes. It can iterate on a change directly in Fern Editor instead of only opening a pull request. + +**Q: What are the requirements?** +A: Editing requires a GitHub repository, because changes are delivered as pull requests; GitLab and other Git providers aren't supported for editing. Analysis and insights work regardless of your Git provider. + +**Q: Is my data used to train AI models?** +A: No. Fern Agent acts with your own Fern permissions, requests are scoped to a single session and aren't retained afterward, and Fern's Devin integration is configured to opt out of any data collection for model training. + diff --git a/fern/products/docs/pages/ai/llms-txt/overview.mdx b/fern/products/docs/pages/ai/llms-txt/overview.mdx index cbc29d53c1..febbe9489b 100644 --- a/fern/products/docs/pages/ai/llms-txt/overview.mdx +++ b/fern/products/docs/pages/ai/llms-txt/overview.mdx @@ -72,3 +72,31 @@ The output format depends on whether you're requesting an individual page or a s + + +## Frequently Asked Questions + +**Q: What's `llms.txt` and why does Fern generate it?** +A: `llms.txt` is a standard for exposing site content to AI developer tools. Fern generates and maintains one automatically so AI tools can discover and index your documentation instead of scraping HTML. + +**Q: How do I view my site's `llms.txt` file?** +A: Fetch `/llms.txt` on your docs domain. It's available at any level of the hierarchy, so `/docs/llms.txt` and `/docs/ai-features/llms.txt` work too. To see what an agent gets for a single page, append `.md` or `.mdx` to the page URL. + +**Q: What's in it?** +A: A one-sentence description and URL for each page, taken from the page's `description` frontmatter (falling back to `subtitle`), plus links to your OpenAPI and AsyncAPI specifications when your site documents endpoints or WebSocket channels. + +**Q: Does Fern generate `llms-full.txt`?** +A: No. Full-site concatenation exceeded most model context windows and added serving overhead for little benefit. Use `llms.txt` to discover pages, then fetch each page's Markdown. + +**Q: How do I exclude a page from `llms.txt`?** +A: Add `noindex: true` to the page's frontmatter. The page stays in your navigation and remains reachable by URL, but drops out of LLM endpoints. + +**Q: What's the difference between `` and ``?** +A: `` content is hidden from the rendered page, Copy page, search, and Ask Fern, but served in `llms.txt` and page Markdown. `` is the inverse: served to human readers, stripped from `llms.txt` and page Markdown. + +**Q: How do I add content that only AI agents see?** +A: Wrap it in ``. It suits programmatic equivalents of UI steps, implementation details, and cross-references that would clutter the page for human readers. See [Customize LLM output](/learn/docs/ai-features/customize-llm-output). + +**Q: Can I serve my own `llms.txt`?** +A: Yes. Point `agents.llms-txt` in `docs.yml` at a file relative to `docs.yml`. It's served at the root `/llms.txt`; nested paths keep using the generated output. + diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index f9e516711a..d556275708 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -104,3 +104,28 @@ 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's the Fern MCP server and how does it work?** +A: It's a [Model Context Protocol](https://modelcontextprotocol.io) server Fern generates and hosts for every site with Ask Fern enabled, served at `your-documentation-site.com/_mcp/server`. AI clients register it as an external data source and get answers about your product from your documentation. + +**Q: How do I enable the MCP server for my Fern docs site?** +A: There's nothing to enable beyond [Ask Fern](/learn/docs/ai-features/ask-fern/overview) — the server and its connection buttons are on by default for sites that have it. + +**Q: Can AI coding assistants like Claude or Cursor use my docs?** +A: Yes. On sites with Ask Fern, the **Connect to Claude Code** and **Connect to Cursor** page actions register the server in one click. Other clients (Claude Desktop, Windsurf, VS Code) add the server URL to their MCP configuration directly. + +**Q: How do MCP clients authenticate on a private docs site?** +A: They must send a `FERN_TOKEN` header containing a valid JWT, obtained from the `get-jwt` endpoint (API key) or the password endpoint (password-protected sites). Without it the server returns only publicly visible content. JWTs expire and there's no automatic refresh in the MCP transport. + +**Q: How do I disable the MCP server?** +A: Set `mcp: false` under `page-actions.options` in `docs.yml`. The endpoint then returns 404, the connection buttons disappear, and agents can no longer discover the server through `llms.txt` or agent prompts. + +**Q: What's the difference between this server and Fern's own MCP server?** +A: This one serves your content to your readers. [Fern's MCP server](/learn/docs/ai-features/fern-mcp-servers) serves Fern's product documentation and your organization's Fern data to the agent you build your site with. + +**Q: What if an agent can't use MCP?** +A: It can fetch your documentation as Markdown over plain HTTP through per-page `.md` URLs and [`llms.txt`](/learn/docs/ai-features/llms-txt), including on authenticated sites. + diff --git a/fern/products/docs/pages/ai/overview.mdx b/fern/products/docs/pages/ai/overview.mdx index 51be0a3225..edacc16fbd 100644 --- a/fern/products/docs/pages/ai/overview.mdx +++ b/fern/products/docs/pages/ai/overview.mdx @@ -51,3 +51,26 @@ Your site is automatically optimized for AI tools and search engines. Fern hosts + + + +## Frequently Asked Questions + +**Q: What AI features does Fern Docs include?** +A: Three groups. Answering questions: [Ask Fern](/learn/docs/ai-features/ask-fern/overview), Ask Fern in Slack, and an [MCP server](/learn/docs/ai-features/mcp-server) for your site. Authoring: [Fern Agent](/learn/docs/ai-features/fern-agent), the `fern-docs` agent skill, [Fern's MCP server](/learn/docs/ai-features/fern-mcp-servers), and AI-generated API examples. Machine readability: [Markdown access](/learn/docs/ai-features/markdown), [`llms.txt`](/learn/docs/ai-features/llms-txt), agent directives, and API catalog discovery. + +**Q: Which AI features are on by default?** +A: The optimizations for AI tools — `llms.txt`, Markdown served in place of HTML to agents, agent directives, and API catalog discovery — are automatic. Ask Fern is enabled from the Dashboard, and Fern Agent is connected from the Dashboard chat panel. + +**Q: Do AI features cost extra?** +A: They're usage-based and consume credits included with your plan: 250 per month on Hobby, 1,000 on Team, and a custom allowance on Enterprise. Ask Fern costs 2 credits per message, an AI-generated example costs 1 credit, and a docs update session in Slack costs 50 credits. + +**Q: Can AI coding assistants like Claude or Cursor use my Fern docs?** +A: Yes, in two ways. They can fetch your pages as Markdown (`llms.txt` plus per-page `.md` URLs), or connect to your site's [MCP server](/learn/docs/ai-features/mcp-server), which is hosted automatically for sites with Ask Fern enabled. + +**Q: What's the difference between the MCP server and `llms.txt`?** +A: The MCP server is a live endpoint an AI client registers as a data source; it answers questions about your product from your content. `llms.txt` is a static file agents fetch over HTTP to discover pages and then read individually. `llms.txt` works on every site; the MCP server requires Ask Fern. + +**Q: What's Fern Agent and how does it help write documentation?** +A: [Fern Agent](/learn/docs/ai-features/fern-agent) edits your docs and analyzes your Fern data from the Dashboard, Slack, or your coding agent over MCP. It delivers changes as pull requests and knows Fern configuration, so navigation entries and redirects come with the change. + diff --git a/fern/products/docs/pages/ask-fern/what-is-ask-fern.mdx b/fern/products/docs/pages/ask-fern/what-is-ask-fern.mdx index 305eb6dbb1..fc7b043d54 100644 --- a/fern/products/docs/pages/ask-fern/what-is-ask-fern.mdx +++ b/fern/products/docs/pages/ask-fern/what-is-ask-fern.mdx @@ -164,3 +164,32 @@ sequenceDiagram A->>U: Return answer with citations ``` + + + +## Frequently Asked Questions + +**Q: How do I enable the Ask Fern AI chat widget on my docs site?** +A: Open the [Fern Dashboard](https://dashboard.buildwithfern.com/), go to **Settings**, and click **Enable** on the Ask AI card. Enabling triggers a reindex of your content, after which the side panel appears on your site. The `ai-search` key in `docs.yml` configures Ask Fern but doesn't turn it on. + +**Q: Can I customize the Ask Fern system prompt?** +A: Yes. Set `ai-search.system-prompt` in `docs.yml` to override Fern's default prompt. + +**Q: What data does Ask Fern use to answer questions?** +A: Your documentation pages and Fern-generated SDK code, indexed as vector embeddings and retrieved per question (RAG), with answers generated by Claude and returned with citations. You can index additional websites and documents through `ai-search.datasources`. + +**Q: How do I configure the verbosity or tone of Ask Fern responses?** +A: Through the custom `system-prompt`, which is where response style, scope, and refusals belong. For specific queries that need a fixed answer, use [guidance](/learn/docs/ai-features/ask-fern/guidance) to override responses. + +**Q: Does Ask Fern support multiple languages?** +A: Fern's [localization](/learn/docs/localization/overview) support for Ask Fern is still in development, so it isn't a configurable setting yet. Language expectations can be stated in the custom system prompt. + +**Q: How do I view Ask Fern conversation analytics?** +A: In the Fern Dashboard: conversations per day, individual conversation drill-down, CSV export, and a resolution rate for the last week, month, or year. Query logs are retained indefinitely unless you set a retention period (1–3650 days) on the **Query log retention** card. + +**Q: Does Ask Fern respect access control?** +A: Yes. It applies your [RBAC](/learn/docs/authentication/features/rbac) settings, so readers only get answers from content their roles allow, down to individual pages and conditional blocks. + +**Q: Can I put Ask Fern somewhere other than my docs site?** +A: Yes — in [Slack](/learn/docs/ai-features/ask-fern/slack-app), in your own React application through the [standalone widgets](/learn/docs/ai-features/search-widget/overview), or in your product through the Ask Fern API. + diff --git a/fern/products/docs/pages/component-library/default-components/overview.mdx b/fern/products/docs/pages/component-library/default-components/overview.mdx index d126ea0d20..da93864f0b 100644 --- a/fern/products/docs/pages/component-library/default-components/overview.mdx +++ b/fern/products/docs/pages/component-library/default-components/overview.mdx @@ -204,3 +204,26 @@ Fern includes 28 built-in components for creating interactive documentation. Sel Display different content based on version selection + + + +## Frequently Asked Questions + +**Q: What built-in components does Fern Docs provide?** +A: 28 components, including accordions, anchors, asides, badges, buttons, callouts, cards, code blocks, copy, download, endpoint request/response/schema snippets, files, frames, icons, `If`, indent, parameter fields, prompts, runnable endpoints, schemas, scroll walkthroughs, steps, tables, tabs, tooltips, and versions. Each card above links to that component's page with its full props and examples. + +**Q: How do I use the `Card`, `CardGroup`, `Callout`, and `Steps` components?** +A: `Card` renders a linkable box (`title`, optional `icon` and `href`) and `CardGroup` lays cards out in a grid with `cols`. `Callout` takes an `intent` and has shortcuts such as `` and ``. `Steps` wraps a sequence of `Step` components for numbered instructions. Component names are case-sensitive and must be closed. + +**Q: Can I create custom MDX components in Fern Docs?** +A: Yes. Add your own [custom React components](/learn/docs/customization/custom-react-components) — server-side rendered — and use them in MDX. For content you want to repeat rather than a component, use [reusable snippets](/learn/docs/writing-content/reusable-snippets) instead. + +**Q: How do I embed a code block with tabs?** +A: Group code blocks with the [tabs](/learn/docs/writing-content/components/tabs) component, or use a [code block](/learn/docs/writing-content/components/code-blocks) group to show the same example in several languages. + +**Q: Is there an AskAIChat component I can embed?** +A: Not as an MDX component — Ask Fern already appears as a side panel on your docs site. To put it in your own application, use the `AskAiChat` component from the [`@fern-api/search-widget` package](/learn/docs/ai-features/search-widget/overview). + +**Q: Do these components work in Fern Editor?** +A: Many do. See the support table in [Fern Editor](/learn/docs/writing-content/fern-editor) for which components can be created and edited visually. + diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index d8d2e327c3..3fdded4f30 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -109,3 +109,32 @@ For more advanced table features like sticky headers for longer datasets, see th ## Fern components Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/writing-content/components/overview) + + + +## Frequently Asked Questions + +**Q: What Markdown features does Fern Docs support?** +A: GitHub Flavored Markdown, including tables written with pipes and hyphens, plus Fern's own component library. Because Fern generates the page `

` from the `page` name in `docs.yml`, start your content at `

`. + +**Q: Can I use MDX in Fern Docs?** +A: Yes. Pages can be `.md` or `.mdx`, and MDX lets you use JSX components inside Markdown. Throughout Fern's documentation, "Markdown" means both. + +**Q: How do I add a page?** +A: Create the file inside your `fern/` folder and reference it from the `navigation` in `docs.yml`. Files that nothing references aren't included in the build. + +**Q: How do I link to another page?** +A: Use the destination's published site path, starting with `/`, and append `#anchor` for a heading. Fern builds these paths from the slugs in your YAML configuration, not from file locations, so file-relative `./` and `../` links aren't supported between pages — they remain correct for media and YAML `path:` references. + +**Q: How do I catch broken links?** +A: The `broken-links` rule in `fern check` (which also runs during `fern docs dev`) validates internal links against your local navigation tree. `fern docs link check`, or the Dashboard link checker, checks a published site including external URLs. + +**Q: How do I add images, videos, and GIFs to Fern Docs pages?** +A: Store them alongside your content and reference them with file-relative paths. See [Images, videos, and embeds](/learn/docs/writing-content/markdown-media). + +**Q: How do I add code blocks with syntax highlighting?** +A: Use fenced code blocks with a language tag, or the [`CodeBlock`](/learn/docs/writing-content/components/code-blocks) component when you want a title, line highlighting, or tabs. + +**Q: How do I add callouts, warnings, and notes?** +A: With the [`Callout`](/learn/docs/writing-content/components/callouts) component or its shortcuts (``, ``, ``, ``). + diff --git a/fern/products/docs/pages/component-library/writing-content/visual-editor.mdx b/fern/products/docs/pages/component-library/writing-content/visual-editor.mdx index 5bebc42a4b..d11eb59ab8 100644 --- a/fern/products/docs/pages/component-library/writing-content/visual-editor.mdx +++ b/fern/products/docs/pages/component-library/writing-content/visual-editor.mdx @@ -104,3 +104,28 @@ Fern Editor supports creating and editing the following components: + + +## Frequently Asked Questions + +**Q: What's the Fern visual editor?** +A: Fern Editor is a WYSIWYG editor for your docs site. Content writers, product managers, and marketers can update pages without code, Markdown, or Git, while every change still lands as a pull request in your repository. + +**Q: How do I access the Fern visual editor?** +A: Connect a Git provider, configure member permissions, then log in to the [Fern Dashboard](https://dashboard.buildwithfern.com/) and open Fern Editor from the **Overview** tab. Admins and Editors can make changes; Viewers have read-only access. + +**Q: Does the Fern editor support GitLab?** +A: Yes, with manual setup: create a GitLab personal access token with the `read_user`, `api`, `write_repository`, `read_repository`, and `read_api` scopes, send it and your repository URL to Fern support, then connect the repository in the Dashboard. Private GitHub and GitLab instances are also supported. + +**Q: Can multiple people edit docs at the same time?** +A: Yes. Multiple team members can edit the same pull request in the Editor, none of whom need GitHub access. + +**Q: How do I trigger a deployment from the Fern editor?** +A: Submitting your changes opens a pull request; merging it runs your normal Fern deployment pipeline. The Editor doesn't publish to production on its own, so your review, CI checks, and branch protections still apply. + +**Q: Does the Fern editor support MDX components?** +A: Many of them. Accordions, accordion groups, buttons, callouts, cards, card groups, code blocks, embeds, endpoint request/response/schema snippets, parameter fields, steps, tables, tabs, and tooltips can be created and edited from the UI; asides, frames, icons, and sticky tables are marked coming soon. You can also switch to dev mode to edit the source directly. + +**Q: What browsers does it support?** +A: Modern Chromium browsers on desktop. Mobile editing and other browsers are listed as coming soon. + diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 947c4a70dd..0bdefcd0ab 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -108,3 +108,32 @@ 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: What's Fern Docs and how does it differ from other documentation tools?** +A: Fern Docs builds a hosted documentation site from three inputs: Markdown pages, an API definition, and a single `docs.yml` configuration file. Unlike a general-purpose static site generator, it generates API Reference pages from your spec (with an API Explorer and SDK code snippets), and ships search, Ask Fern, an MCP server, and `llms.txt` without extra setup. + +**Q: How does Fern generate documentation from an API definition?** +A: Reference your spec from the `api.specs` section of `generators.yml`, then add an `- api: API Reference` entry to your `docs.yml` navigation. `fern generate --docs` merges the spec with your Markdown content and publishes the combined site. See [How Fern Docs work](/learn/docs/getting-started/how-it-works). + +**Q: Does Fern support both API Reference docs and hand-written Markdown pages?** +A: Yes. Hand-written `.md`/`.mdx` pages and generated API Reference sections live side by side in the same `docs.yml` navigation tree. + +**Q: Can I use Fern Docs without using Fern SDKs?** +A: Yes. Docs and SDKs are separate products. A docs site needs only `docs.yml` and `fern.config.json` (plus `generators.yml` if you publish an API Reference). SDK generators are configured in the `groups` section of `generators.yml`, and are required only if you also want [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. + +**Q: What file formats does Fern Docs support for API definitions?** +A: OpenAPI (YAML or JSON), AsyncAPI, OpenRPC, gRPC/protobuf, and the Fern Definition. + +**Q: How do I get started with Fern Docs for the first time?** +A: Install the CLI (`npm install -g fern-api`), create a `fern` folder from the [starter template](https://github.com/fern-api/docs-starter) or with `fern init --docs`, preview with `fern docs dev`, then publish with `fern generate --docs`. The [Docs quickstart](/learn/docs/getting-started/quickstart) covers each step. + +**Q: Is Fern Docs open source?** +A: The Fern CLI and generators are developed in public in the [`fern-api/fern`](https://github.com/fern-api/fern) repository. Fern Docs itself is a hosted product: building and serving your site runs on Fern's infrastructure, with a [self-hosted](/learn/docs/self-hosted/overview) Docker image available on the Enterprise plan. + +**Q: What hosting options does Fern Docs support?** +A: By default Fern hosts your site at the `docs.buildwithfern.com` URL configured in `docs.yml`. You can serve it from your own [subdomain, subpath, or root domain](/learn/docs/preview-publish/setting-up-your-domain), and Enterprise customers can [self-host](/learn/docs/self-hosted/overview) the site on their own infrastructure. + diff --git a/fern/products/docs/pages/getting-started/how-it-works.mdx b/fern/products/docs/pages/getting-started/how-it-works.mdx index 945d475303..f2cc938973 100644 --- a/fern/products/docs/pages/getting-started/how-it-works.mdx +++ b/fern/products/docs/pages/getting-started/how-it-works.mdx @@ -142,3 +142,26 @@ flowchart TD CLI == ④ Deploys updated docs ==> Server[Fern Docs Server] ``` + + + +## Frequently Asked Questions + +**Q: How does Fern convert an OpenAPI spec into documentation?** +A: `fern generate --docs` sends your API specs, `docs.yml`, MDX files, and media to the Fern Docs microservice, which merges them into a single site, indexes the content for search, and deploys the result to Fern's hosting layer with an embedded API Explorer. + +**Q: What's the Fern CLI and how does it work?** +A: The [Fern CLI](/learn/cli-api-reference/cli-reference/overview) (`fern-api` on npm or Homebrew) is the entry point for every Fern workflow: it initializes a project, validates it with `fern check`, previews it with `fern docs dev`, and publishes it with `fern generate --docs`. In CI, the same command runs inside a GitHub Action. + +**Q: How does Fern handle versioning of documentation?** +A: Documentation versions are declared in your `docs.yml` navigation, so each version gets its own navigation tree and URL prefix. See [Versions](/learn/docs/configuration/versions). + +**Q: What's the relationship between the `fern/` folder and the docs output?** +A: The `fern/` folder is the source: `docs.yml`, `fern.config.json`, API definitions, MDX pages, and assets. Nothing is served from it directly — the CLI compiles it and Fern hosts the compiled site. See [Project structure](/learn/docs/getting-started/project-structure). + +**Q: How does Fern keep docs in sync with API changes?** +A: When a pull request merges, a Fern GitHub Action fetches your API specification (including from a separate repository) and reruns `fern generate --docs`, so the API Reference is regenerated from the current spec on every deploy. + +**Q: Do I have to edit files in Git to update my docs?** +A: No. You can open a pull request in the docs repository yourself, or use [Fern Editor](/learn/docs/writing-content/fern-editor), where the Fern GitHub App opens the pull request for you. Either way, merging triggers the same deployment pipeline. + diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index 0f99c28af0..ade3213b4c 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -194,4 +194,25 @@ The `fern.config.json` file stores your organization name and the Fern CLI versi When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/learn/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details. + +## Frequently Asked Questions + +**Q: What files are required in the `fern` folder?** +A: `fern.config.json` (organization name and CLI version) and `docs.yml` (navigation, theme, hosting) are required. Add `generators.yml` and an API definition when you publish an API Reference, plus MDX pages, assets, snippets, and `styles.css` as needed. The `fern` and `changelog` folder names are reserved; other folder names are yours to choose. + +**Q: What's the purpose of `generators.yml`?** +A: It points the CLI at your API definitions through the `api.specs` section, and optionally configures SDK generation through its `groups` section. + +**Q: What's the purpose of `docs.yml`?** +A: `docs.yml` controls navigation structure, visual design, site functionality, and hosting. Only files referenced in its navigation (or discovered through a `folder` configuration) are included in a build. + +**Q: How do I add multiple API definitions to one Fern project?** +A: Put each API in its own subfolder of a folder named exactly `apis`, each with its own spec and `generators.yml`, then reference each one in `docs.yml` with an `api-name` that matches the subfolder name. + +**Q: Where do I put my OpenAPI spec in the `fern` folder?** +A: Anywhere inside `fern/` (the root or a subfolder), in YAML or JSON, then reference it from `generators.yml` under `api.specs`. Fern treats `.yml` and `.yaml` identically. + +**Q: Why isn't my new page showing up?** +A: A page appears only when `docs.yml` references it, either through a `page` entry or an auto-populated `folder` entry. Unreferenced files are ignored during the build. + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index fb60a7a8fd..c52859c07e 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: How do I publish my first Fern docs site?** +A: Install the CLI, create a `fern` folder (starter template or `fern init --docs`), set your organization in `fern.config.json` and your docs URL in `docs.yml`, then run `fern generate --docs`. The site is published at the `instances[].url` you configured. + +**Q: What's the `fern generate --docs` command?** +A: It builds your docs — Markdown, media, `docs.yml` settings, and any API definition — and publishes the result to the URL in `docs.yml`. Add `--preview` to publish to a temporary preview URL instead of production, and `--no-prompt` to skip the interactive confirmation in CI. + +**Q: How do I preview my docs locally before publishing?** +A: Run `fern docs dev` for a hot-reloading local server, or `fern generate --docs --preview` for a shareable preview link. + +**Q: What's a `docs.yml` file and what does it configure?** +A: `docs.yml` is the manifest for the whole site: hosting instances and custom domains, the navigation tree, tabs, versions and products, branding (logo, colors, favicon, typography), layout, navbar and footer links, redirects, analytics, and AI settings. See the [site settings reference](/learn/docs/configuration/site-level-settings). + +**Q: How do I connect my GitHub repository to Fern Docs?** +A: Install the [Fern GitHub app](https://github.com/apps/fern-api) and [connect the repository](/learn/dashboard/configuration/github-repo) in the [Fern Dashboard](https://dashboard.buildwithfern.com/). The Dashboard also manages organization members and your CLI version — there are no CLI equivalents for those tasks. + +**Q: Can I use Fern Docs with an existing OpenAPI spec?** +A: Yes. Run `fern init --openapi /path/to/openapi.yml` (a local path or URL) to scaffold the project around your spec, then add `- api: "API Reference"` to your `docs.yml` navigation. + +**Q: How long does it take to publish docs with Fern?** +A: This quickstart is designed to take under five minutes end to end: install the CLI, initialize the `fern` folder, configure your organization and URL, and publish. + diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 7869127e8d..4582050f41 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1343,3 +1343,35 @@ 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 Fern Docs?** +A: In the `navigation` key of `docs.yml` (or a product YAML file), where you list `page`, `section`, `api`, `changelog`, and `link` entries in the order they should appear. See [Navigation](/learn/docs/configuration/navigation). + +**Q: How do I add tabs or sections to my docs site?** +A: Declare tabs under the `tabs` key with a display name and icon, then nest each tab's `layout` inside `navigation`. Sections are `section` entries with a `contents` list, and they can be nested. For larger sites, [products](/learn/docs/configuration/products) group whole navigation trees. + +**Q: How do I set a custom logo, colors, and fonts in Fern Docs?** +A: `logo` takes light and dark files plus an optional height and href; `colors` sets `accent-primary` and other colors per light/dark mode, with `accent-primary` the only required one; `typography` configures body, heading, and code fonts from files you ship in the repo. + +**Q: How do I add a custom domain to my Fern docs site?** +A: Add `custom-domain` to the instance in `docs.yml` (a string, or a list for multiple domains), then complete DNS setup. See [Bring your custom domain](/learn/docs/preview-publish/setting-up-your-domain). + +**Q: How do I configure redirects in Fern Docs?** +A: Under `redirects`, as `source`/`destination` pairs. Sources can be exact paths or patterns such as `/old-folder/:slug*`. See [Configure redirects](/learn/docs/seo/redirects). + +**Q: How do I enable or disable the search bar?** +A: Search is on by default. Set `settings.disable-search: true` to turn it off, for example when you use a custom search solution. + +**Q: How do I add navbar links to my docs site?** +A: Under `navbar-links`, each entry typed as `minimal`, `filled`, `github`, or `dropdown`, with text, an href, and optional icon and target. + +**Q: How do I set up versioning in Fern Docs?** +A: Define versions in your navigation configuration so each version gets its own tree and URL prefix. See [Versions](/learn/docs/configuration/versions). + +**Q: What's the difference between an instance and a custom domain?** +A: An instance is the backend of a distinct docs site, published to its own `docs.buildwithfern.com` URL and selected with `fern generate --docs --instance ` — typically one for staging and one for production. `custom-domain` is the vanity domain that fronts an instance. + diff --git a/fern/products/docs/pages/preview-publish/setting-up-your-domain.mdx b/fern/products/docs/pages/preview-publish/setting-up-your-domain.mdx index 34f5b5bafa..f28e1c3b3d 100644 --- a/fern/products/docs/pages/preview-publish/setting-up-your-domain.mdx +++ b/fern/products/docs/pages/preview-publish/setting-up-your-domain.mdx @@ -237,3 +237,32 @@ instances: ``` Listing extra domains in `docs.yml` doesn't activate them on its own. Contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to register and verify each additional domain. You'll receive DNS configuration details for each. + + + +## Frequently Asked Questions + +**Q: How do I set up a custom domain for my Fern docs site?** +A: Add `custom-domain` to the instance in `docs.yml`, contact Fern for your CNAME and TXT values, and create those DNS records. The [Fern Dashboard](/learn/dashboard/configuration/custom-domains) is the recommended path — it provides the correct records for your domain type automatically. + +**Q: Can I use a subdomain like `docs.mycompany.com` with Fern?** +A: Yes. This is the simplest setup: a CNAME record for the subdomain pointing at the value Fern gives you, plus the TXT record for domain verification. If you use Cloudflare, make sure the record isn't proxied. + +**Q: Can I use a subpath like `mycompany.com/docs` with Fern?** +A: Yes, on the Team plan and above. Append the subpath to both `url` and `custom-domain` in `docs.yml` — they must share the same basepath, or `fern check` and publishing fail — and set up a [reverse proxy](/learn/docs/preview-publish/reverse-proxy) that forwards requests to Fern's origin with the `x-fern-host` header. A subpath can't be routed with DNS alone. + +**Q: Can I serve docs from my root domain?** +A: Yes. Set `custom-domain` to `www.mydomain.com`, then add a CNAME for `www`, an A record for the apex domain, and the TXT verification record. Requests to the bare domain redirect to `www`. + +**Q: How do I configure DNS for my Fern docs custom domain?** +A: In your registrar's DNS settings, using the records Fern sends you: a CNAME (subdomain or `www`), an A record for an apex domain, and a TXT record for verification. + +**Q: How long does it take for a custom domain to go live?** +A: The domain resolves once Fern completes setup and your DNS records propagate, which typically takes a few minutes globally. Confirm from an incognito window or a mobile device. + +**Q: Does Fern support SSL/HTTPS for custom domains?** +A: Yes. Fern provisions the SSL certificate automatically once your records are in place; propagation can take a few minutes. + +**Q: Can one docs site serve several domains?** +A: Yes. List multiple values under `custom-domain` for partner or white-label deployments. Listing them doesn't activate them — contact Fern to register and verify each one and receive its DNS records. + diff --git a/fern/products/docs/pages/self-hosted/self-hosted.mdx b/fern/products/docs/pages/self-hosted/self-hosted.mdx index 7ede2b90dc..d6cd13baf6 100644 --- a/fern/products/docs/pages/self-hosted/self-hosted.mdx +++ b/fern/products/docs/pages/self-hosted/self-hosted.mdx @@ -102,7 +102,28 @@ sequenceDiagram The self-hosted container includes [health check endpoints](./health-check-endpoints) on port 8081 for Kubernetes and Helm deployments. + +## Frequently Asked Questions +**Q: Can I self-host Fern Docs?** +A: Yes, on the Enterprise plan. Fern provides your documentation site as a Docker container you deploy on your own infrastructure. Fern's managed hosting remains the recommendation unless you have requirements that rule it out. +**Q: What are the requirements for self-hosting Fern Docs?** +A: A server that can run Docker, the organization access token Fern gives you to pull `fernenterprise/fern-self-hosted` from Docker Hub, and your `fern` folder. You own server setup, security, maintenance, upgrades to new image releases, and how the site is exposed to readers. +**Q: How does self-hosted Fern Docs differ from the cloud-hosted version?** +A: The content and site features are the same, but anything that depends on a connection to Fern's cloud services is unavailable, and deployment is on your schedule: Fern releases new images and your team evaluates and deploys them. + +**Q: What features are available in self-hosted mode?** +A: Core site features work, including API References, the API Explorer, the component library, custom branding, CSS/JS and React components, custom domains, navigation, tabs, products, versions, search, SEO metadata, redirects, reusable snippets, SDK code snippets, `llms.txt`, embedded mode, health check endpoints, password protection, JWT authentication, and page-level access control. + +**Q: What isn't available when self-hosting?** +A: Ask Fern, AI-generated examples, Fern Agent, Fern Editor, analytics and integrations (including Intercom), OAuth, SSO, and RBAC. PDF export and offline AI chat are in development — [contact Fern](mailto:support@buildwithfern.com) if you need them. + +**Q: How do I monitor a self-hosted deployment?** +A: The container exposes [health check endpoints](/learn/docs/self-hosted/health-check-endpoints) on port 8081 for Kubernetes and Helm deployments. + +**Q: How do I set it up?** +A: Log in to Docker Hub with the token from Fern, pull the image, add your `fern` folder to the container, run it, and deploy it in your environment. See [Set up self-hosted documentation](/learn/docs/self-hosted/set-up). + diff --git a/fern/products/sdks/fern-folder.mdx b/fern/products/sdks/fern-folder.mdx index 2a08d3bf5f..7077ec5710 100644 --- a/fern/products/sdks/fern-folder.mdx +++ b/fern/products/sdks/fern-folder.mdx @@ -69,3 +69,26 @@ Now that you have a working SDK, set up GitHub repositories and configure publis Learn about Fern's multi-repo file structure and GitHub setup. + + + +## Frequently Asked Questions + +**Q: How do I generate my first SDK with Fern?** +A: Install the CLI, run `fern init` (optionally with `--openapi `), then run `fern generate`. The default configuration produces a TypeScript SDK in `sdks/typescript`. + +**Q: What's `generators.yml` and how do I configure it?** +A: `generators.yml` points the CLI at your API definition through `api.specs` and declares generator `groups` — one per SDK — each with a generator name, version, and output location. `fern generate` with no flags runs the `default-group`. The [`generators.yml` reference](/learn/sdks/reference/generators-yml) documents every field. + +**Q: How do I run `fern generate` to produce an SDK?** +A: `fern generate` runs the default group. Use `fern generate --group ` for one group, `--api ` in multi-API projects, and `--version ` to set the published SDK version. + +**Q: How do I preview an SDK locally before publishing?** +A: Run `fern generate --preview`. The SDK is written to a local `.preview/` folder and nothing is published to GitHub or a package registry. + +**Q: How do I set up GitHub Actions to auto-publish my SDK?** +A: Change the generator's output `location` from `local-file-system` to the target registry and add a `github` block in `generators.yml`. Follow your language's publishing guide — for example [Publishing to npm](/learn/sdks/generators/typescript/publishing) — for the repository and credential setup. + +**Q: Where does the generated SDK go?** +A: To the output configured for the group. The default `local-file-system` output writes into your repository (for example `../sdks/typescript`); other options publish to a GitHub repository or a package registry. + diff --git a/fern/products/sdks/how-it-works.mdx b/fern/products/sdks/how-it-works.mdx index 81038b0cb2..4506538c62 100644 --- a/fern/products/sdks/how-it-works.mdx +++ b/fern/products/sdks/how-it-works.mdx @@ -77,3 +77,26 @@ Rate limits apply only to cloud generation. [Local generation](/learn/sdks/deep- If your team needs higher quotas, contact support@buildwithfern.com. + + + +## Frequently Asked Questions + +**Q: What happens when I run `fern generate`?** +A: Fern allocates cloud compute, pulls the Docker image for the generator version pinned in `generators.yml`, generates the core SDK files, verifies your organization, adds package metadata (`package.json`, `pyproject.toml`, README, dependencies), and writes the finished SDK to the output configured for that group. + +**Q: Do I need Docker installed to generate SDKs?** +A: Not for the default cloud generation. Docker is required only for local generation with `fern generate --local`, which runs the generator image on your own machine. + +**Q: Can SDK generation run on my own infrastructure?** +A: Yes. `fern generate --local` performs [self-hosted generation](/learn/sdks/deep-dives/self-hosted) for organizations with security or compliance requirements, and it isn't subject to cloud generation quotas. + +**Q: Why did I only get partial SDK files?** +A: Package metadata is added after organization verification. Without a verified organization, generation produces core code only, without the package distribution files. + +**Q: Are there limits on how often I can generate?** +A: Cloud generation uses a leaky bucket with a burst capacity of 10 generations and a refill rate of 5 generations per minute. Contact support@buildwithfern.com for higher quotas. + +**Q: Does generation require authentication?** +A: Cloud generation does — log in with `fern login` or set `FERN_TOKEN`. Local generation with `--local` doesn't. + diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 57ca62637b..2610118a35 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -288,3 +288,29 @@ 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 programming languages does Fern support for SDK generation?** +A: TypeScript, Python, Go, Java, .NET (C#), PHP, Ruby, Swift, and Rust are generally available. C++ and Kotlin are available by [request](https://buildwithfern.com/book-demo?type=language-request). + +**Q: How does Fern generate SDKs from an OpenAPI spec?** +A: You reference your spec in `generators.yml` and declare one generator group per language. `fern generate` runs each generator on Fern's cloud infrastructure and writes the finished SDK to the configured output: your local filesystem, a GitHub repository, or a package registry. See [How SDKs work](/learn/sdks/overview/how-it-works). + +**Q: How do Fern-generated SDKs compare to other SDK generators?** +A: Fern's documentation doesn't benchmark other generators. What Fern documents about its own output is idiomatic, strongly typed clients with [auto-pagination](/learn/sdks/deep-dives/auto-pagination), [retries with backoff](/learn/sdks/deep-dives/retries-with-backoff), OAuth token refresh, [webhook signature verification](/learn/sdks/deep-dives/webhook-signature-verification), [idempotency headers](/learn/sdks/deep-dives/idempotency), server-sent events, WebSocket clients, generated tests, and customizations that survive regeneration. + +**Q: Do Fern SDKs support pagination, retries, and OAuth automatically?** +A: Yes, once configured. Auto-pagination, retries with backoff, and OAuth token refresh are built-in capabilities driven by your API definition and `generators.yml` — you don't hand-write that logic. + +**Q: Can I customize the generated SDK code?** +A: Yes, in two ways. List files in `.fernignore` to own them end to end, or use [Replay](/learn/sdks/overview/custom-code#replay) for line-level edits to generated files, which are reapplied by 3-way merge on every regeneration. + +**Q: How do I publish a Fern SDK to npm, PyPI, or Maven?** +A: Set the generator's output `location` to the registry (for example `npm`, `pypi`, or `maven`) in `generators.yml` and configure GitHub publishing. Each language section has its own publishing guide, such as [Publishing to npm](/learn/sdks/generators/typescript/publishing). + +**Q: What's the difference between Fern SDKs and hand-written SDKs?** +A: Generated SDKs stay in lockstep with your API definition: regenerating picks up spec changes across every language at once. Hand-written code you still need lives alongside the generated code, protected by `.fernignore` or tracked as a Replay patch. +