Publishing your docs | Fern Documentation

When you are ready for your docs to be publicly accessible, publish them using the Fern CLI. To validate changes with reviewers first, generate preview links. Choose one of the following approaches: publish only to a production site, or to separate staging and production sites.

Use the Fern Dashboard to manage CLI access, connect your GitHub repository, and monitor analytics and broken links.

Publish to production

For a single production site (no staging environment), run the following command to publish your documentation:

fern generate --docs

Example

fern generate --docs
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
[docs]: ✓ All checks passed
[docs]: Published docs to https://plantstore.docs.buildwithfern.com
┌─
│ ✓  https://plantstore.docs.buildwithfern.com
└─

Automate publishing process

Use a GitHub Action workflow to publish your docs when a push is made to the main branch. Publishing runs on any CI provider that can install the CLI and read a FERN_TOKEN secret: for GitLab, use the GitLab CI/CD pipeline.

Generate API key

Use fern token to generate an API key for authenticating the Fern CLI in CI/CD environments. The API key is specific to your organization defined in fern.config.json and doesn’t expire. You can also create and manage API keys from the API keys page in the Dashboard.

terminal

fern token

Add API key as a secret

Add the API key as a repository secret called FERN_TOKEN.

Create workflow

Create a Publish Docs workflow (example), and reference the secret.

.github/workflows/publish-docs.yml

name: Publish Docs
on:
  push:
    branches:
      - main
jobs:
  run:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Fern
        run: npm install -g fern-api
      - name: Publish Docs
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: fern generate --docs

Publish to staging and production

To preview changes on a staging site before publishing to production, define multiple instances in your docs.yml file. Once you configure multiple instances, you must use the --instance flag when publishing.

Configure instances

Add both staging and production URLs to your docs.yml file. Don’t include https:// in the URLs.

docs.yml

instances:
  - url: plantstore-prod.docs.buildwithfern.com
  - url: plantstore-staging.docs.buildwithfern.com

Publish to a specific instance

Use the --instance flag to publish to a specific environment:

# Publish to staging
fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
# Publish to production
fern generate --docs --instance plantstore-prod.docs.buildwithfern.com

After publishing, both instances will appear in the Fern Dashboard.

Automate publishing process

Use GitHub Action workflows to automatically deploy to staging on every push, while keeping production deployments manual.

Generate API key

terminal

fern token

Add API key as a secret

Add the API key as a repository secret called FERN_TOKEN.

Set up automatic staging deployment workflow

This workflow automatically publishes to your staging instance when changes are pushed to the main branch:

.github/workflows/publish-staging.yml

name: Publish Staging Docs
on:
  workflow_dispatch:
  push:
    branches:
      - main
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Fern
        run: npm install -g fern-api
      - name: Validate configuration
        run: fern check
      - name: Publish to Staging
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: fern generate --docs --instance plantstore-staging.docs.buildwithfern.com

Set up manual production deployment workflow

This workflow allows you to manually trigger a production deployment from the GitHub Actions UI:

.github/workflows/publish-production.yml

name: Publish Production Docs
on:
  workflow_dispatch:
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Fern
        run: npm install -g fern-api
      - name: Validate configuration
        run: fern check
      - name: Publish to Production
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: fern generate --docs --instance plantstore-prod.docs.buildwithfern.com

To deploy to production, go to the Actions tab in your GitHub repository, select the workflow, and click Run workflow.

Hosting

When you publish your docs, Fern takes care of hosting them for you. You can also publish your docs to a custom domain.

Self-hosting your docs

If you need access to your docs offline or would like to host your docs on your own server, Fern offers that option as well. Self-hosted docs have limited access to certain features (including Ask Fern and analytics).

Unpublishing your docs

To unpublish a docs site, navigate to the Settings page for your site in the Fern Dashboard and click Unpublish. This makes the domain no longer publicly accessible, but doesn’t delete the site — you can republish it at any time. This is useful for creating draft sites or temporarily hiding a site from public view.