> This page is for Docs.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# 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.

#### System architecture

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<br />--docs"]]

    %% AWS VPC section
    subgraph vpc ["Fern AWS VPC"]
        direction LR
        MICROSERVICE["Fern Docs<br />microservice"]
        DATABASE[("Database")]
        S3[("S3")]
    end

    %% External services
    SERVICES["External Services<br />(UpStash, Algolia, PostHog,<br />TurboPuffer, AI Inference)"]

    %% Vercel hosting
    subgraph vercel ["Vercel"]
        direction LR
        STATIC["Static site"]
        EXPLORER["API explorer"]
        EDGE["Vercel Edge<br />(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.

> **Info**
>
> 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) 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.

#### Editing and deployment workflows

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]
```