Pull request previews

PR previews offer a way to preview changes from pull requests (PRs) before merging code to a production branch. This is useful for reviewing documentation changes before publishing them to your live documentation site. Use manually or in GitHub Actions.

Usage

$fern generate --docs --preview

Example

$fern generate --docs --preview
>
>[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
>[docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com
>┌─
>│ ✓  docs.example.com
>└─

Usage in GitHub Actions

The following is a GitHub Action workflow that generates a preview URL for every pull request. Be sure to add the FERN_TOKEN for your organization to the repository.

.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              id: generate-docs
19              env:
20                  FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
21              run: |
22                  OUTPUT=$(fern generate --docs --preview 2>&1) || true
23                  echo "$OUTPUT"
24                  URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
25                  echo "Preview URL: $URL"
26                  echo "🌿 Preview your docs: $URL" > preview_url.txt
27
28            - name: Comment URL in PR
29              uses: thollander/actions-comment-pull-request@v2.4.3
30              with:
31                  filePath: preview_url.txt
Allow PR previews to be generated from forks

Fern’s PR previews GitHub Action requires a Fern token to run. Depending on your repository’s permissions, you may need to use the following workflow to allow PR previews from forks to access this token.

.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  # Only for commenting
13      contents: read        # For checking out code
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        if: github.event_name == 'pull_request_target'
23        run: |
24          git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }}
25          git checkout pr-${{ github.event.pull_request.number }}    
26
27      - name: Generate preview URL
28        id: generate-docs
29        env:
30          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
31        run: |
32          OUTPUT=$(fern generate --docs --preview 2>&1) || true
33          echo "$OUTPUT"
34          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
35          echo "Preview URL: $URL"
36          echo "🌿 Preview your docs: $URL" > preview_url.txt
37
38      - name: Comment URL in PR
39        uses: thollander/actions-comment-pull-request@v2.4.3
40        with:
41          filePath: preview_url.txt

Preview links do not expire. However, the time to live (TTL) is subject to change in the future.

Built with