Preview & publish

Preview changes

View as Markdown

Fern offers two ways to preview documentation changes:

Prerequisites

Install the following:

Local development

Run a local preview server to view documentation changes instantly with hot reload. Offline access is available after the first online run.

$ # Start preview server (from directory containing fern folder)
>  fern docs dev
>
>  # Or use a custom port
>  fern docs dev --port 3002

Your documentation will be available at http://localhost:3000 (default) or the port you specified. If you attempt to run Fern on a port that’s already in use, it will use the next available port.

Some features are disabled in local development:

  • Search
  • SEO (favicon, auto-generated meta tags, etc.)
  • Authentication

Generate shareable preview URLs to review and collaborate on documentation changes before publishing. Each preview link includes a unique UUID and isn’t indexed by search engines. Links don’t expire.

$fern generate --docs --preview
Example output
$[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
>[docs]: Published docs to https://fern-preview-c973a36e-337b-44f5-ab83-aab.docs.buildwithfern.com/learn
>┌─
>│ ✓  docs.example.com
>└─

Automate with GitHub Actions

Generate preview links automatically for every pull request by adding a GitHub Actions workflow. Add your FERN_TOKEN to the repository secrets before using these workflows.

.github/workflows/preview-docs.yml
1name: Preview Docs
2
3on:
4  pull_request
5
6jobs:
7  run:
8    runs-on: ubuntu-latest
9    permissions: write-all
10    steps:
11      - name: Checkout repository
12        uses: actions/checkout@v4
13
14      - name: Install Fern
15        run: npm install -g fern-api
16
17      - name: Generate preview URL
18        env:
19          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
20        run: |
21          OUTPUT=$(fern generate --docs --preview 2>&1) || true
22          echo "$OUTPUT"
23          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
24          echo "🌿 Preview your docs: $URL" > preview_url.txt
25
26      - name: Comment URL in PR
27        uses: thollander/actions-comment-pull-request@v2.4.3
28        with:
29          filePath: preview_url.txt

If your repository accepts contributions from forks, use pull_request_target instead of pull_request to allow the workflow to access your FERN_TOKEN secret:

.github/workflows/preview-docs.yml
1name: Preview Docs
2
3on:
4  pull_request_target:
5    branches:
6      - main
7
8jobs:
9  run:
10    runs-on: ubuntu-latest
11    permissions:
12      pull-requests: write
13      contents: read
14    steps:
15      - name: Checkout repository
16        uses: actions/checkout@v4
17
18      - name: Install Fern
19        run: npm install -g fern-api
20
21      - name: Checkout PR
22        run: |
23          git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }}
24          git checkout pr-${{ github.event.pull_request.number }}
25
26      - name: Generate preview URL
27        env:
28          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
29        run: |
30          OUTPUT=$(fern generate --docs --preview 2>&1) || true
31          echo "$OUTPUT"
32          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
33          echo "🌿 Preview your docs: $URL" > preview_url.txt
34
35      - name: Comment URL in PR
36        uses: thollander/actions-comment-pull-request@v2.4.3
37        with:
38          filePath: preview_url.txt