# Fern Docs > Build beautiful, interactive documentation websites with Fern Docs. Create API references, custom components, and AI-powered features in under 5 minutes.
{/* Dashed Pattern - Left Side */} {/* Dashed Pattern - Right Side */}

Get started

Build a docs site quickly by importing your existing styling and specs.

Quickstart
Quickstart Arrow right light Arrow right light

Set up a documentation site in under 5 minutes.

Configure with ease
Configure with ease Arrow right light Arrow right light

Use one simple file to generate documentation that fits your brand.

Features

Build your own components, enable Ask Fern, generate API references, and easily update your docs.

Flexible component library
Flexible component library Arrow right light Arrow right light

Use pre-built or custom React components for a polished look.

Fern Editor
Fern Editor Arrow right light Arrow right light

Modify your documentation without touching code and publish to your GitHub.

API Specs
Bring your own API spec Arrow right light Arrow right light

Use OpenAPI, AsyncAPI, gRPC, OpenRPC, and the Fern spec.

AI features
AI features Arrow right light Arrow right light

AI-native features including Ask Fern and auto-generated MCP servers.

Self-host your docs
Self-host your docs Arrow right light Arrow right light

Deploy on your own infrastructure to meet security or compliance requirements.

MCP server for your site
MCP server for your site Arrow right light Arrow right light

Auto-generated MCP server for AI client integration.

# How Fern Docs work > Learn how Fern transforms your API specifications and documentation into a unified developer experience Fern combines your API specifications, static Markdown files (like how-to guides and tutorials), media assets (images, videos, etc.), and custom settings defined in your `docs.yml` file to generate a beautiful, interactive hosted documentation site. This process is built around two major workflows: **editing** and **deploying** your documentation. This diagram shows the technical infrastructure that powers the documentation generation process. ```mermaid flowchart TD %% Input sources at the top subgraph inputs ["Input Sources"] API["API Specs"] DOCS["Docs.yml"] MDX["MDX files"] MEDIA["Media content"] end %% Generation process GENERATE[["fern generate
--docs"]] %% AWS VPC section subgraph vpc ["Fern AWS VPC"] direction LR MICROSERVICE["Fern Docs
microservice"] DATABASE[("Database")] S3[("S3")] end %% External services SERVICES["External Services
(UpStash, Algolia, PostHog,
TurboPuffer, AI Inference)"] %% Vercel hosting subgraph vercel ["Vercel"] direction LR STATIC["Static site"] EXPLORER["API explorer"] EDGE["Vercel Edge
(Middleware)"] end %% External connections as hexagons CLOUDFLARE{{"Cloudflare (CORS)"}} WORKOS{{"WorkOS"}} CUSTOMER{{"Customer API"}} USER(("User")) %% Vertical flow connections API --> GENERATE DOCS --> GENERATE MDX --> GENERATE MEDIA --> GENERATE GENERATE --> MICROSERVICE MICROSERVICE --> SERVICES SERVICES <--> STATIC STATIC --> CLOUDFLARE EXPLORER <--> CLOUDFLARE EDGE <--> WORKOS CLOUDFLARE --> CUSTOMER EDGE <--> USER %% Internal connections MICROSERVICE -.-> DATABASE MICROSERVICE -.-> S3 ``` ## Content workflows You can update your documentation in two ways: * **Direct editing**: Open a pull request directly in the [GitHub repository that contains your docs](/learn/docs/getting-started/project-structure) (including your `docs.yml` configuration and Markdown files). * **Fern Editor**: Use the [Fern Editor](/learn/docs/writing-content/fern-editor) to modify your docs without touching code. The Fern GitHub App fetches the current state from your docs repository and passes it to the Fern Editor. When you submit changes, the Fern GitHub App automatically opens a pull request for review. After the update goes through your review process, an approver can merge it. You can use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members (add or remove), domains, and Fern CLI version. ## Deployment workflows When a pull request is merged into your docs repository, an automated pipeline transforms your content into a live documentation site and syncs it with your API changes in three main stages: ### Trigger GitHub Action and fetch API specs The merged PR triggers a Fern GitHub Action. The action retrieves your API specification from a separate repository using secure token authentication. The GitHub Action only has access to the specific docs repository from which it's running. ### Generate and process content [The Fern CLI](/learn/cli-api-reference/cli-reference/overview) runs `fern generate --docs` to merge your API specs with documentation content. Behind the scenes, this process involves several key components: * **Input processing**: The system combines your API specification files, `docs.yml` configuration file, `.mdx` files, and media content. * **Core infrastructure**: The generation process runs on Fern's AWS VPC infrastructure, where the Fern Docs microservice acts as the central orchestrator. This microservice coordinates content processing while connecting to a database for storing indexed content and S3 for asset storage. * **Content indexing**: During generation, Fern automatically indexes your documentation content to enable search functionality across your entire site. This indexing integrates with external services: [Algolia](/learn/docs/customization/search) for advanced search capabilities, UpStash for caching, PostHog for analytics, TurboPuffer for vector storage, and AI inference services (Bedrock, Claude) for intelligent content processing. ### Deploy to hosting platform The processed content is deployed to Vercel as a documentation site with an embedded [API explorer](/learn/docs/api-references/api-explorer/overview) that allows users to test endpoints directly within the documentation. Vercel Edge middleware handles the underlying routing, authentication, and performance optimization. The deployed documentation site integrates with external systems like Cloudflare for CORS management and WorkOS for enterprise authentication. This diagram shows how content flows from editing to deployment. ```mermaid flowchart TD FE[Fern Editor] U[User] DR[Docs Repo] CLI[Fern CLI] Decision{Make a PR or edit in Fern Editor?} Spec((API Spec Repo)) GA[GitHub Actions] U ==> Decision Decision == Make edit ==> FE Decision == Open and Merge PR ==> DR FE <== Fetches state and opens PR ==> DR DR == ① Merged PR triggers deployment flow ==> GA Spec <-. ② Fetches and merges API spec .-> GA GA == ③ Triggers doc regeneration ==> CLI CLI == ④ Deploys updated docs ==> Server[Fern Docs Server] ``` # Quickstart > Learn how to build beautiful developer documentation with Fern in under 5 minutes. Install CLI, add Markdown content, generate API references, and publish. Build beautiful developer documentation that [matches your brand](https://buildwithfern.com/customers) with Fern. Fern supports writing pages in Markdown and generating API Reference documentation from an OpenAPI Specification. Follow this guide to get started with Fern in under 5 minutes. Migrating from existing documentation? Fern provides a white-glove migration service as part of the Enterprise plan. [Reach out here](https://buildwithfern.com/contact). Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line: ```bash npm install -g fern-api ``` All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch ```bash title="SSH" git clone git@github.com:fern-api/docs-starter.git ``` ```bash title="HTTPS" git clone https://github.com/fern-api/docs-starter.git ``` You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files. ```bash fern init --docs ``` You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files): Configure two settings (these values don't have to match): * **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/)) * **Docs URL** in `docs.yml`: Determines where your docs are published ```json {2} { "organization": "{{YOUR_ORGANIZATION}}", "version": "3.31.2" } ``` ```yml {2} instances: - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com ``` Use only alphanumeric characters, hyphens, and underscores for both values. Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more. Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages. ```markdown docs/pages/hello-world.mdx --- title: "Page Title" description: "Subtitle (optional)" --- Hello world! ``` Reference your new pages from your `docs.yml` file. You can reference the Markdown page within a section or as a standalone page. ```yml docs.yml navigation: - page: Hello World path: docs/pages/hello-world.mdx - section: Overview contents: - page: Getting Started path: docs/pages/getting-started.mdx ``` If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec: ```bash fern init --openapi /path/to/openapi.yml ``` Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref): ```yml docs.yml navigation: - api: "API Reference" ``` [Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file. ```yml maxLines=7 colors: accent-primary: dark: "#f0c193" light: "#af5f1b" logo: dark: docs/assets/logo-dark.svg light: docs/assets/logo-light.svg height: 40 href: https://buildwithfern.com/ favicon: docs/assets/favicon.svg ``` Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links. Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files: ```bash fern docs dev ``` Generate a preview URL you can share with your team: ```bash fern generate --docs --preview ``` When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs): ```bash fern generate --docs ``` This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`). Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs. ## Explore Fern's features Now that your docs are live, explore these features to enhance them further. Use the `docs.yml` file to configure colors, SEO, typography, layouts, and more. Use Fern's built-in components to create interactive, well-organized documentation. Add products, versions, nested sections, tabs, and more. Use the Fern Editor to let non-technical team members edit docs in a WYSIWYG browser interface. Host your docs on your own domain or subdomain (e.g., docs.example.com). Integrate with PostHog, Segment, Intercom, Google Tag Manager, and other platforms. # Project structure > An overview of the file and folder structure of a Fern Docs project This page provides an overview of the file and folder structure of a Fern Docs project. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs. ## Top-level folders A Fern Docs project has the following top-level folders: * `pages`: Contains the Markdown (MDX) files that make up your documentation. * `assets`: Contains any images or videos used in your documentation. * `docs.yml`: Defines the navigation, theme, and hosting details of your documentation. * `openapi` or `definition/`: Contains your API specification files (if you have an API Reference section). * `generators.yml`: Required for OpenAPI to reference your spec location. Also used to configure SDK generation. Not required for Fern Definition docs-only projects. * `fern.config.json`: The configuration file specifying your organization name and CLI version. ## Pages folder The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation. The `pages` folder is organized into subfolders based on the sections of your documentation. Each subfolder contains the MDX files for the pages in that section. ## Assets folder The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths. ## `docs.yml` The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings. For complete configuration options, see the [docs.yml reference](/docs/configuration/site-level-settings). ```yml instances: - url: fern.docs.buildwithfern.com/learn custom-domain: buildwithfern.com/learn navigation: - section: Introduction layout: - page: QuickStart path: pages/introduction/quickstart.mdx - page: Project Structure path: pages/introduction/project-structure.mdx - page: Showcase path: pages/introduction/showcase.mdx navbar-links: - type: filled text: Book a demo url: https://buildwithfern.com/contact logo: light: ./images/logo-primary.svg dark: ./images/logo-white.svg colors: accent-primary: dark: "#ADFF8C" light: "#209d63" favicon: ./images/favicon.ico title: Fern's Documentation ``` ## API definitions and `generators.yml` To generate [API Reference](/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. How you do this depends on your format: * **OpenAPI/AsyncAPI**: Always requires a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation. * **Fern Definition**: Auto-detected when you have a `definition/` directory. Only add `generators.yml` if you're generating SDKs. Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/docs/api-references/sdk-snippets) in your API Reference. The `openapi` folder contains your OpenAPI Specification file. Fern supports either YAML or JSON format. You must also create a `generators.yml` file that references your spec: ```yaml title="generators.yml" api: specs: - openapi: ../openapi/openapi.json ``` In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. To see this in practice, check out [Fluidstack's Fern configuration](https://github.com/fluidstackio/fern-config/tree/main/fern/openapi). The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. Fern automatically detects this directory, so no `generators.yml` is needed for API Reference documentation. You can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. [See an example](https://github.com/fern-api/fern/tree/3137938b70e058f3691ddef34d5c1cc29acc4b80/test-definitions/fern/apis/imdb/definition). Organize multiple APIs into separate folders. You can mix OpenAPI and Fern Definition formats: Reference each API in `docs.yml` using `api-name` that matches the folder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). ## `fern.config.json` The `fern.config.json` file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds. ```json title="fern.config.json" { "organization": "plant-catalog", "version": "3.31.2" } ``` When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details. # December 20, 2025 ## Custom SVG icons in card and icon components The Card and Icon components support relative paths to SVG files. Use a relative path like `./images/icon.svg` to display custom SVG icons from your project. ```jsx Markdown Card with a custom SVG icon. Custom SVG icon ``` Learn more about the [Card](/learn/docs/writing-content/components/cards) and [Icon](/learn/docs/writing-content/components/icons) components. # December 16, 2025 ## Embedded mode You can now hide the header and footer from your documentation pages by adding `?embedded=true` to any URL. This makes it easy to embed your docs in iframes, dashboards, or other contexts where you want to display only the content. Once enabled, embedded mode persists across navigation events within the same session. [Learn more](/learn/docs/customization/embedded-mode) about embedded mode. # December 15, 2025 ## Custom page actions Define custom page action buttons with your own titles, icons, and URLs. Custom actions appear alongside the built-in page actions like Copy Page and View as Markdown, and can link to external tools, editors, or any URL. ```yaml docs.yml page-actions: options: custom: - title: Open in Windsurf subtitle: Edit with AI assistance url: "windsurf://open?url={url}" icon: fa-solid fa-wind default: true ``` Custom actions support URL placeholders like `{slug}`, `{domain}`, and `{url}` to dynamically insert page information into the link. [Learn more](/learn/docs/configuration/site-level-settings#custom-page-actions) about configuring custom page actions. # December 14, 2025 ## AI-enhanced examples Fern automatically generates realistic request and response examples for your API Reference using AI. Instead of placeholder values like `"string"` and `1.1`, your examples contain believable data based on your OpenAPI spec's endpoint properties and descriptions. These examples stay in sync with your spec - when you change or add fields, the generated examples update automatically. You can customize the style of generated examples, edit them directly, or disable the feature entirely. [Learn more](/learn/docs/ai-features/ai-examples) about AI-enhanced examples. # December 11, 2025 ## Logo right-text property You can now display custom text to the right of your logo image using the new `right-text` property in your logo configuration. This is useful for adding labels like "Docs" or "API" next to your logo. ```yaml docs.yml logo: dark: assets/images/logo-dark.svg light: assets/images/logo-light.svg right-text: Docs ``` [Learn more](/learn/docs/configuration/site-level-settings#logo-configuration) about the logo configuration options. ## Canvas body theme A new `canvas` body theme option wraps your main content area in a card-like container with rounded corners and a subtle border. This creates a more contained, focused reading experience that visually separates your documentation content from the sidebar and header. ```yaml docs.yml theme: body: canvas ``` The canvas theme applies to all page layouts including guides, overviews, and API reference pages. It uses your configured `card-background` color and `border` color for consistent styling with your site's color scheme. [Learn more](/learn/docs/configuration/site-level-settings#theme-configuration) about theme configuration options. # December 10, 2025 ## Schema snippet component The new `` component displays type definitions from your API Reference as a JSON code block. Use it alongside the `` component to show both a JSON representation and the detailed field breakdown of your data models.
```jsx Markdown ``` [Learn more](/learn/docs/writing-content/components/schema-snippet) about the Schema Snippet component. # December 9, 2025 ## Last updated frontmatter property You can now display a "Last updated" message in the page footer using the new `last-updated` frontmatter property. This helps readers know when the content was last modified. ```mdx --- title: API Reference last-updated: December 9, 2025 --- ``` The date is displayed as-is in small text below the on-page feedback, so you can use any date format you prefer. [Learn more](/learn/docs/configuration/page-level-settings#last-updated) about the `last-updated` frontmatter property. ## Footer component for API Reference descriptions You can now use the `