Preview & publish

Publishing your docs

View as Markdown

When you are ready for your docs to be publicly accessible, publish them using the Fern CLI. 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 and your GitHub repository connection.

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
>└─

Use a GitHub Action workflow to publish your docs when a push is made to the main branch.

1

Generate token

Use fern token to generate a token for authenticating the Fern CLI in CI/CD environments. The token is specific to your organization defined in fern.config.json and doesn’t expire.

terminal
$fern token
2

Add token as a secret

Add the token as a repository secret called FERN_TOKEN.

3

Create workflow

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

.github/workflows/publish-docs.yml
1name: Publish Docs
2
3on:
4  push:
5    branches:
6      - main
7
8jobs:
9  run:
10    runs-on: ubuntu-latest
11    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
12    steps:
13      - name: Checkout repository
14        uses: actions/checkout@v4
15
16      - name: Install Fern
17        run: npm install -g fern-api
18
19      - name: Publish Docs
20        env:
21          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
22        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.

1

Configure instances

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

docs.yml
1instances:
2  - url: plantstore-prod.docs.buildwithfern.com
3  - url: plantstore-staging.docs.buildwithfern.com
2

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.

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

1

Generate token

Use fern token to generate a token for authenticating the Fern CLI in CI/CD environments. The token is specific to your organization defined in fern.config.json and doesn’t expire.

terminal
$fern token
2

Add token as a secret

Add the token as a repository secret called FERN_TOKEN.

3

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
1name: Publish Staging Docs
2
3on:
4  workflow_dispatch:
5  push:
6    branches:
7      - main
8
9jobs:
10  run:
11    runs-on: ubuntu-latest
12    steps:
13      - name: Checkout repository
14        uses: actions/checkout@v4
15
16      - name: Install Fern
17        run: npm install -g fern-api
18
19      - name: Validate configuration
20        run: fern check
21
22      - name: Publish to Staging
23        env:
24          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
25        run: fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
4

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
1name: Publish Production Docs
2
3on:
4  workflow_dispatch:
5
6jobs:
7  run:
8    runs-on: ubuntu-latest
9    steps:
10      - name: Checkout repository
11        uses: actions/checkout@v4
12
13      - name: Install Fern
14        run: npm install -g fern-api
15
16      - name: Validate configuration
17        run: fern check
18
19      - name: Publish to Production
20        env:
21          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
22        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

If you need to take down your docs site, you cannot directly unpublish it. However, you can replace your content with an empty site to effectively remove all of your documentation.

1

Clear your navigation

Replace the navigation object in your docs.yml file with an empty list.

docs.yml
1instances:
2  - <organization>.docs.buildwithfern.com
3navigation: []
2

Deploy the empty site

Publish the updated configuration by running fern generate --docs. This will remove all content from your site, and users visiting any page will see a 404 error.