-
Notifications
You must be signed in to change notification settings - Fork 4
Condense pages on previewing docs into a single page #2520
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -102,3 +102,4 @@ exceptions: | |
| - SSG | ||
| - REST | ||
| - MDN | ||
| - UUID | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
118 changes: 0 additions & 118 deletions
118
fern/products/docs/pages/getting-started/pr-preview.mdx
This file was deleted.
Oops, something went wrong.
159 changes: 111 additions & 48 deletions
159
fern/products/docs/pages/getting-started/preview-changes-locally.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,76 +1,139 @@ | ||
| --- | ||
| title: "Preview changes locally" | ||
| subtitle: "View and share updates to your documentation" | ||
| description: "View and share updates to your documentation" | ||
| title: Preview changes | ||
| description: Preview changes to your docs locally or with shareable preview links. | ||
| --- | ||
|
|
||
| Fern offers two ways to preview changes to your documentation: a [local development environment](#local-development) and [unique preview links](#generate-a-preview-link). | ||
| Fern offers two ways to preview documentation changes: | ||
|
|
||
| ## Local development | ||
|
|
||
| Fern enables you to view changes to your documentation in a locally hosted environment. | ||
|
|
||
| <Info>**Prerequisite**: Please install Node.js (version 18+) before proceeding.</Info> | ||
|
|
||
| Follow these steps to install and run the Fern CLI: | ||
|
|
||
| **Step 1**: Install the Fern CLI: | ||
|
|
||
| <CodeGroup> | ||
|
|
||
| ```bash npm | ||
| npm i -g fern-api | ||
| ``` | ||
| - **[Local development](#local-development)**: Fast iteration with hot reload, best for active development | ||
| - **[Preview links](#preview-links)**: Shareable URLs for reviews and collaboration | ||
|
|
||
| ```bash yarn | ||
| yarn global add fern-api | ||
| ``` | ||
| <Info title="Prerequisites"> | ||
| Install the following: | ||
| - Node.js version 18 or higher | ||
| - [The Fern CLI](/learn/cli-api-reference/cli-reference/overview#install-fern-cli) | ||
| </Info> | ||
|
|
||
| </CodeGroup> | ||
| ## Local development | ||
|
|
||
| **Step 2**: Navigate to the docs directory (where the `fern` folder is located) and execute the following command: | ||
| [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. | ||
|
|
||
| ```bash | ||
| fern docs dev | ||
| # Start preview server (from directory containing fern folder) | ||
| fern docs dev | ||
|
|
||
| # Or use a custom port | ||
| fern docs dev --port 3002 | ||
| ``` | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| <Note> | ||
| Some features are disabled in the local development environment, including: | ||
| Some features are disabled in local development: | ||
| - Search | ||
| - SEO (favicon, auto-generated meta tags, etc.) | ||
| - Authentication | ||
| - Authentication | ||
| </Note> | ||
|
|
||
| ### Custom ports | ||
| ## Preview links | ||
|
|
||
| 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: | ||
|
|
||
| ```bash | ||
| fern docs dev --port 3002 | ||
| ``` | ||
|
|
||
| If you attempt to run Fern on a port that's already in use, it will use the next available port: | ||
|
|
||
| ## Generate a preview link | ||
|
|
||
| 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). | ||
|
|
||
| **Usage**: | ||
| 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. | ||
|
|
||
| ```bash | ||
| fern generate --docs --preview | ||
| ``` | ||
|
|
||
| **Example**: | ||
|
|
||
| ```bash | ||
| fern generate --docs --preview | ||
|
|
||
| ```bash 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](/learn/cli-api-reference/cli-reference/commands#fern-token) before using these workflows. | ||
|
|
||
| <CodeBlock title = ".github/workflows/preview-docs.yml"> | ||
| ```yaml | ||
| name: Preview Docs | ||
|
|
||
| on: | ||
| pull_request | ||
|
|
||
| jobs: | ||
| run: | ||
| runs-on: ubuntu-latest | ||
| permissions: write-all | ||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Install Fern | ||
| run: npm install -g fern-api | ||
|
|
||
| - name: Generate preview URL | ||
| env: | ||
| FERN_TOKEN: ${{ secrets.FERN_TOKEN }} | ||
| run: | | ||
| OUTPUT=$(fern generate --docs --preview 2>&1) || true | ||
| echo "$OUTPUT" | ||
| URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') | ||
| echo "🌿 Preview your docs: $URL" > preview_url.txt | ||
|
|
||
| - name: Comment URL in PR | ||
| uses: thollander/actions-comment-pull-request@v2.4.3 | ||
| with: | ||
| filePath: preview_url.txt | ||
| ``` | ||
| </CodeBlock> | ||
|
|
||
| <Accordion title="For repositories that accept pull requests from forks"> | ||
|
|
||
| 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: | ||
|
|
||
| <CodeBlock title = ".github/workflows/preview-docs.yml"> | ||
| ```yaml | ||
| name: Preview Docs | ||
|
|
||
| on: | ||
| pull_request_target: | ||
| branches: | ||
| - main | ||
|
|
||
| jobs: | ||
| run: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| pull-requests: write | ||
| contents: read | ||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Install Fern | ||
| run: npm install -g fern-api | ||
|
|
||
| - name: Checkout PR | ||
| run: | | ||
| git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }} | ||
| git checkout pr-${{ github.event.pull_request.number }} | ||
|
|
||
| - name: Generate preview URL | ||
| env: | ||
| FERN_TOKEN: ${{ secrets.FERN_TOKEN }} | ||
| run: | | ||
| OUTPUT=$(fern generate --docs --preview 2>&1) || true | ||
| echo "$OUTPUT" | ||
| URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') | ||
| echo "🌿 Preview your docs: $URL" > preview_url.txt | ||
|
|
||
| - name: Comment URL in PR | ||
| uses: thollander/actions-comment-pull-request@v2.4.3 | ||
| with: | ||
| filePath: preview_url.txt | ||
| ``` | ||
| </CodeBlock> | ||
|
|
||
| </Accordion> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated