|
1 | 1 | --- |
2 | | -title: "Preview changes locally" |
3 | | -subtitle: "View and share updates to your documentation" |
4 | | -description: "View and share updates to your documentation" |
| 2 | +title: Preview changes |
| 3 | +description: Preview changes to your docs locally or with shareable preview links. |
5 | 4 | --- |
6 | 5 |
|
7 | | -Fern offers two ways to preview changes to your documentation: a [local development environment](#local-development) and [unique preview links](#generate-a-preview-link). |
| 6 | +Fern offers two ways to preview documentation changes: |
8 | 7 |
|
9 | | -## Local development |
10 | | - |
11 | | -Fern enables you to view changes to your documentation in a locally hosted environment. |
12 | | - |
13 | | -<Info>**Prerequisite**: Please install Node.js (version 18+) before proceeding.</Info> |
14 | | - |
15 | | -Follow these steps to install and run the Fern CLI: |
16 | | - |
17 | | -**Step 1**: Install the Fern CLI: |
18 | | - |
19 | | -<CodeGroup> |
20 | | - |
21 | | -```bash npm |
22 | | -npm i -g fern-api |
23 | | -``` |
| 8 | +- **[Local development](#local-development)**: Fast iteration with hot reload, best for active development |
| 9 | +- **[Preview links](#preview-links)**: Shareable URLs for reviews and collaboration |
24 | 10 |
|
25 | | -```bash yarn |
26 | | -yarn global add fern-api |
27 | | -``` |
| 11 | +<Info title="Prerequisites"> |
| 12 | +Install the following: |
| 13 | +- Node.js version 18 or higher |
| 14 | +- [The Fern CLI](/learn/cli-api-reference/cli-reference/overview#install-fern-cli) |
| 15 | +</Info> |
28 | 16 |
|
29 | | -</CodeGroup> |
| 17 | +## Local development |
30 | 18 |
|
31 | | -**Step 2**: Navigate to the docs directory (where the `fern` folder is located) and execute the following command: |
| 19 | +[Run a local preview server](/learn/cli-api-reference/cli-reference/commands#fern-docs-dev) to view documentation changes instantly with hot reload. Offline access is available after the first online run. |
32 | 20 |
|
33 | 21 | ```bash |
34 | | -fern docs dev |
| 22 | + # Start preview server (from directory containing fern folder) |
| 23 | + fern docs dev |
| 24 | + |
| 25 | + # Or use a custom port |
| 26 | + fern docs dev --port 3002 |
35 | 27 | ``` |
36 | 28 |
|
37 | | -A local preview of your documentation will be available at `http://localhost:3000`. The functionality is available offline if you have run local development mode online at least once. |
| 29 | +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. |
38 | 30 |
|
39 | 31 | <Note> |
40 | | -Some features are disabled in the local development environment, including: |
| 32 | +Some features are disabled in local development: |
41 | 33 | - Search |
42 | 34 | - SEO (favicon, auto-generated meta tags, etc.) |
43 | | -- Authentication |
| 35 | +- Authentication |
44 | 36 | </Note> |
45 | 37 |
|
46 | | -### Custom ports |
| 38 | +## Preview links |
47 | 39 |
|
48 | | -By default, Fern uses port 3000. You can customize the port on which Fern runs by using the `--port` flag. For example, to run Fern on port 3002, use this command: |
49 | | - |
50 | | -```bash |
51 | | -fern docs dev --port 3002 |
52 | | -``` |
53 | | - |
54 | | -If you attempt to run Fern on a port that's already in use, it will use the next available port: |
55 | | - |
56 | | -## Generate a preview link |
57 | | - |
58 | | -Fern allows you to generate a shareable preview link that displays the current state of your docs. Each preview link is appended with a UUID and is not indexed. Currently, these links do not expire (this behavior is subject to change in the future). |
59 | | - |
60 | | -**Usage**: |
| 40 | +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. |
61 | 41 |
|
62 | 42 | ```bash |
63 | 43 | fern generate --docs --preview |
64 | 44 | ``` |
65 | 45 |
|
66 | | -**Example**: |
67 | | - |
68 | | -```bash |
69 | | -fern generate --docs --preview |
70 | | - |
| 46 | +```bash Example output |
71 | 47 | [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. |
72 | 48 | [docs]: Published docs to https://fern-preview-c973a36e-337b-44f5-ab83-aab.docs.buildwithfern.com/learn |
73 | 49 | ┌─ |
74 | 50 | │ ✓ docs.example.com |
75 | 51 | └─ |
76 | | -``` |
| 52 | +``` |
| 53 | + |
| 54 | +### Automate with GitHub Actions |
| 55 | + |
| 56 | +Generate preview links automatically for every pull request by adding a GitHub Actions workflow. [Add your `FERN_TOKEN` to the repository secrets](/learn/cli-api-reference/cli-reference/commands#fern-token) before using these workflows. |
| 57 | + |
| 58 | +<CodeBlock title = ".github/workflows/preview-docs.yml"> |
| 59 | +```yaml |
| 60 | +name: Preview Docs |
| 61 | + |
| 62 | +on: |
| 63 | + pull_request |
| 64 | + |
| 65 | +jobs: |
| 66 | + run: |
| 67 | + runs-on: ubuntu-latest |
| 68 | + permissions: write-all |
| 69 | + steps: |
| 70 | + - name: Checkout repository |
| 71 | + uses: actions/checkout@v4 |
| 72 | + |
| 73 | + - name: Install Fern |
| 74 | + run: npm install -g fern-api |
| 75 | + |
| 76 | + - name: Generate preview URL |
| 77 | + env: |
| 78 | + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} |
| 79 | + run: | |
| 80 | + OUTPUT=$(fern generate --docs --preview 2>&1) || true |
| 81 | + echo "$OUTPUT" |
| 82 | + URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') |
| 83 | + echo "🌿 Preview your docs: $URL" > preview_url.txt |
| 84 | +
|
| 85 | + - name: Comment URL in PR |
| 86 | + uses: thollander/actions-comment-pull-request@v2.4.3 |
| 87 | + with: |
| 88 | + filePath: preview_url.txt |
| 89 | +``` |
| 90 | +</CodeBlock> |
| 91 | +
|
| 92 | +<Accordion title="For repositories that accept pull requests from forks"> |
| 93 | +
|
| 94 | +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: |
| 95 | + |
| 96 | +<CodeBlock title = ".github/workflows/preview-docs.yml"> |
| 97 | +```yaml |
| 98 | +name: Preview Docs |
| 99 | +
|
| 100 | +on: |
| 101 | + pull_request_target: |
| 102 | + branches: |
| 103 | + - main |
| 104 | +
|
| 105 | +jobs: |
| 106 | + run: |
| 107 | + runs-on: ubuntu-latest |
| 108 | + permissions: |
| 109 | + pull-requests: write |
| 110 | + contents: read |
| 111 | + steps: |
| 112 | + - name: Checkout repository |
| 113 | + uses: actions/checkout@v4 |
| 114 | +
|
| 115 | + - name: Install Fern |
| 116 | + run: npm install -g fern-api |
| 117 | +
|
| 118 | + - name: Checkout PR |
| 119 | + run: | |
| 120 | + git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }} |
| 121 | + git checkout pr-${{ github.event.pull_request.number }} |
| 122 | +
|
| 123 | + - name: Generate preview URL |
| 124 | + env: |
| 125 | + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} |
| 126 | + run: | |
| 127 | + OUTPUT=$(fern generate --docs --preview 2>&1) || true |
| 128 | + echo "$OUTPUT" |
| 129 | + URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') |
| 130 | + echo "🌿 Preview your docs: $URL" > preview_url.txt |
| 131 | +
|
| 132 | + - name: Comment URL in PR |
| 133 | + uses: thollander/actions-comment-pull-request@v2.4.3 |
| 134 | + with: |
| 135 | + filePath: preview_url.txt |
| 136 | +``` |
| 137 | +</CodeBlock> |
| 138 | + |
| 139 | +</Accordion> |
0 commit comments