diff --git a/fern/products/docs/pages/getting-started/capabilities.mdx b/fern/products/docs/pages/getting-started/capabilities.mdx index 947c4a70dd..890363627c 100644 --- a/fern/products/docs/pages/getting-started/capabilities.mdx +++ b/fern/products/docs/pages/getting-started/capabilities.mdx @@ -108,3 +108,27 @@ 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 + +### What can I build with Fern Docs? +Fern Docs lets you build a complete developer documentation site: write pages in Markdown, generate API references from OpenAPI or other specs, add interactive components, enable AI search with Ask Fern, protect content with authentication and role-based access control, localize into multiple languages, and publish to a custom domain. + +### Does Fern Docs support API reference generation? +Yes. Fern Docs generates interactive API reference pages from OpenAPI, AsyncAPI, gRPC, and OpenRPC specifications. The API Explorer lets readers send real requests directly from the docs with prefilled authentication. + +### Can I password-protect or restrict access to my Fern docs? +Yes. Fern Docs supports password protection, SSO, JWT, and OAuth for authentication. Role-based access control (RBAC) lets you show or hide specific content based on each reader's role. + +### Does Fern Docs support multiple languages (localization)? +Yes. Fern Docs has built-in localization support, allowing you to ship documentation in multiple languages from a single source repository. + +### Can I self-host Fern Docs on my own infrastructure? +Yes. Fern Docs supports self-hosting so you can deploy the documentation site on your own servers or cloud infrastructure. + +### What analytics integrations does Fern Docs support? +Fern Docs can forward analytics events to PostHog, Segment, Mixpanel, and other providers. The Fern Dashboard also provides built-in traffic analytics. + + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index fb60a7a8fd..fe79a62aee 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -409,3 +409,27 @@ 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 + +### How do I get started with Fern Docs? +Install the Fern CLI with `npm install -g fern-api` or `brew install fern-api`, then run `fern init --docs` to create a new project, or clone the [docs-starter template](https://github.com/fern-api/docs-starter). Configure your organization name in `fern.config.json` and your docs URL in `docs.yml`, then run `fern generate --docs` to publish. + +### How long does it take to publish a Fern docs site? +Most teams publish their first docs site in under 5 minutes using the starter template. The CLI handles building and deploying automatically. + +### Can I preview my Fern docs before publishing? +Yes. Run `fern docs dev` to start a local development server with hot-reloading, or run `fern generate --docs --preview` to generate a shareable preview URL you can send to teammates. + +### How do I add an API reference to my Fern docs? +Add your OpenAPI spec to the project (or run `fern init --openapi /path/to/spec.yml`), then reference it in `docs.yml` with `- api: "API Reference"`. Fern will generate interactive API reference pages automatically on the next publish. + +### How do I publish Fern docs in a CI/CD pipeline? +Set the `FERN_TOKEN` environment variable (generate a token with `fern token`) and run `fern generate --docs --no-prompt` to skip the interactive menu. Store the token as a repository secret named `FERN_TOKEN` in GitHub Actions. + +### Can non-technical teammates edit Fern docs? +Yes. The Fern Editor is a visual, WYSIWYG editing interface in the Fern Dashboard that lets teammates without Git access write and update documentation pages. + + diff --git a/fern/products/docs/pages/preview-publish/reverse-proxy.mdx b/fern/products/docs/pages/preview-publish/reverse-proxy.mdx index 13146592ea..68439d024c 100644 --- a/fern/products/docs/pages/preview-publish/reverse-proxy.mdx +++ b/fern/products/docs/pages/preview-publish/reverse-proxy.mdx @@ -325,3 +325,27 @@ curl -sI https://mydomain.com/docs | grep -i "^age:" If `content-type` is `text/x-component` instead of `text/html`, your proxy is forwarding the viewer's `Host` header to Fern's origin. Ensure the `Host` header sent to the origin is `app.buildwithfern.com`. If the `age` header is present and non-zero, your proxy is serving a cached response. Revisit your provider's configuration to ensure HTML caching is disabled. + + + +## Frequently Asked Questions + +### When do I need a reverse proxy for Fern Docs? +You need a reverse proxy when you host Fern Docs on a subpath of your domain (e.g. `mydomain.com/docs`). Subdomain setups (e.g. `docs.mydomain.com`) use a CNAME record instead and do not require a reverse proxy. + +### Which reverse proxy providers does Fern support? +Fern provides configuration guides for Cloudflare Workers, AWS CloudFront, Netlify, Vercel, Nginx, Akamai, and Caddy. + +### What headers does my reverse proxy need to send to Fern? +Every proxied request must include two headers: `x-fern-host` set to your bare domain (e.g. `mydomain.com`) and `Host` set to `app.buildwithfern.com`. The `x-fern-host` header tells Fern which docs site to serve. + +### Should I cache HTML responses from Fern in my reverse proxy? +No. You must not cache HTML responses. Fern sets `Cache-Control: public, max-age=0, must-revalidate` on HTML pages. Caching HTML causes pages to reference JavaScript and CSS from older deployments that no longer exist, breaking the site. + +### How do I verify my reverse proxy is configured correctly? +Run `curl -sI https://mydomain.com/docs | grep -i content-type` and confirm the response is `text/html`. If you see `text/x-component`, your proxy is forwarding the wrong `Host` header. Also check that the `age` header is absent or zero to confirm HTML is not being cached. + +### Why does my Fern docs subpath return raw component data instead of HTML? +This happens when your reverse proxy forwards the viewer's `Host` header to Fern's origin instead of setting it to `app.buildwithfern.com`. Fern's origin uses the `Host` header for routing and returns raw React Server Component payloads when it receives an unrecognized host. + + diff --git a/fern/products/home/pages/welcome.mdx b/fern/products/home/pages/welcome.mdx index c7d982f404..d4bd2dce78 100644 --- a/fern/products/home/pages/welcome.mdx +++ b/fern/products/home/pages/welcome.mdx @@ -434,3 +434,24 @@ Fern offers lightning-fast support. If you're a customer, reach out via your ded - [Email us](mailto:support@buildwithfern.com) - [Book a demo](https://buildwithfern.com/book-demo) + + + +## Frequently Asked Questions + +### What is Fern? +Fern is a developer tooling platform that generates SDKs in TypeScript, Python, Go, Java, C#, PHP, Ruby, Swift, and Rust from your API definition, and publishes beautiful, interactive API documentation websites — all from a single source of truth. + +### What API specification formats does Fern support? +Fern supports OpenAPI, AsyncAPI, OpenRPC, and gRPC. You can use one or more of these specs to generate both SDKs and documentation. + +### Does Fern generate SDKs automatically? +Yes. Fern reads your API definition and generates idiomatic, production-ready client libraries in multiple languages. The generated SDKs include type safety, error handling, pagination, retries, and more. + +### What is Ask Fern? +Ask Fern is an AI-powered search feature built into Fern Docs. It lets readers ask natural-language questions and get instant answers sourced directly from your documentation. + +### Can I use Fern for both SDKs and documentation? +Yes. Fern is designed to handle both. You can generate SDKs, publish docs, or do both from the same API definition and configuration. + + diff --git a/fern/products/sdks/introduction.mdx b/fern/products/sdks/introduction.mdx index 57ca62637b..ba678376e4 100644 --- a/fern/products/sdks/introduction.mdx +++ b/fern/products/sdks/introduction.mdx @@ -288,3 +288,24 @@ 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 + +### What programming languages does Fern support for SDK generation? +Fern generates SDKs in TypeScript, Python, Go, Java, .NET (C#), PHP, Ruby, Swift, and Rust. + +### How do I generate an SDK with Fern? +Define your API using OpenAPI or another supported spec, configure a generator in `generators.yml`, and run `fern generate`. Fern produces an idiomatic client library for each configured language. + +### Are Fern-generated SDKs production-ready? +Yes. Fern-generated SDKs include type safety, error handling, automatic retries, pagination helpers, and follow the idiomatic conventions of each language. Many companies ship Fern-generated SDKs directly to their customers. + +### Can I publish Fern-generated SDKs to package registries? +Yes. Fern can publish generated SDKs directly to npm (TypeScript), PyPI (Python), Maven (Java), NuGet (.NET), Packagist (PHP), RubyGems (Ruby), and other registries as part of the generation pipeline. + +### Does Fern keep SDKs in sync with my API? +Yes. Every time you update your API definition and run `fern generate`, Fern regenerates the SDKs to reflect the latest changes. You can automate this with GitHub Actions so SDKs are always up to date. + +