diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 9736ae5ae..e26021d65 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -102,3 +102,4 @@ exceptions: - SSG - REST - MDN + - UUID diff --git a/fern/docs.yml b/fern/docs.yml index 13917b7c5..d3a739cd2 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -298,7 +298,7 @@ redirects: - source: /learn/docs/getting-started/global-configuration destination: /learn/docs/configuration/site-level-settings - source: /learn/docs/getting-started/development - destination: /learn/docs/preview-publish/previewing-changes-locally + destination: /learn/docs/preview-publish/preview-changes - source: /learn/docs/getting-started/publish-your-docs destination: /learn/docs/preview-publish/publishing-your-docs @@ -334,7 +334,11 @@ redirects: - source: /learn/docs/navigation/hiding-content destination: /learn/docs/customization/hiding-content - source: /learn/docs/building-and-customizing-your-docs/pull-request-preview - destination: /learn/docs/preview-publish/previewing-changes-in-a-pr + destination: /learn/docs/preview-publish/preview-changes + - source: /learn/docs/preview-publish/previewing-changes-in-a-pr + destination: /learn/docs/preview-publish/preview-changes + - source: /learn/docs/preview-publish/previewing-changes-locally + destination: /learn/docs/preview-publish/preview-changes - source: /learn/docs/building-and-customizing-your-docs/product-switching destination: /learn/docs/configuration/products - source: /learn/docs/navigation/products diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 79768e9bb..4dbc41a87 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -162,10 +162,8 @@ navigation: - section: Preview & publish collapsed: true contents: - - page: Previewing changes locally + - page: Preview changes path: ./pages/getting-started/preview-changes-locally.mdx - - page: Previewing changes in a PR - path: ./pages/getting-started/pr-preview.mdx - page: Publishing your docs path: ./pages/getting-started/publishing-your-docs.mdx - page: Setting up your domain diff --git a/fern/products/docs/pages/authentication/sso.mdx b/fern/products/docs/pages/authentication/sso.mdx index 79b47ff96..bf1999039 100644 --- a/fern/products/docs/pages/authentication/sso.mdx +++ b/fern/products/docs/pages/authentication/sso.mdx @@ -14,7 +14,7 @@ Fern’s Single Sign-On (SSO) is an enterprise feature that lets your team secur When SSO is enabled for your organization, authenticated users of Fern can: - **Use the Fern Editor**: Make edits to your docs from the browser -- **Send Authenticated Preview Links** Only authenticated users can view [preview links](/learn/docs/preview-publish/previewing-changes-locally) +- **Send Authenticated Preview Links** Only authenticated users can view [preview links](/learn/docs/preview-publish/preview-changes#preview-links) ## How it works diff --git a/fern/products/docs/pages/getting-started/pr-preview.mdx b/fern/products/docs/pages/getting-started/pr-preview.mdx deleted file mode 100644 index 19493cf04..000000000 --- a/fern/products/docs/pages/getting-started/pr-preview.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Pull request previews -description: Fern's PR previews feature lets you preview changes to your docs from pull requests before merging to the live docs site. Use manually or in GitHub Actions. ---- - -`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 - -```bash -fern generate --docs --preview -``` - -## Example - -```bash -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](/learn/cli-api/cli-reference/commands#fern-token). - - -```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 - id: generate-docs - 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 URL: $URL" - 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 -``` - - - - 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. - - - ```yaml .github/workflows/preview-docs.yml - name: preview-docs - - on: - pull_request_target: - branches: - - main - - jobs: - run: - runs-on: ubuntu-latest - permissions: - pull-requests: write # Only for commenting - contents: read # For checking out code - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Install Fern - run: npm install -g fern-api - - - name: Checkout PR - if: github.event_name == 'pull_request_target' - 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 - id: generate-docs - 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 URL: $URL" - 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 - ``` - - - -## Link expiration - -Preview links do not expire. However, the time to live (TTL) is subject to change in the future. diff --git a/fern/products/docs/pages/getting-started/preview-changes-locally.mdx b/fern/products/docs/pages/getting-started/preview-changes-locally.mdx index d5757d944..0acc2d152 100644 --- a/fern/products/docs/pages/getting-started/preview-changes-locally.mdx +++ b/fern/products/docs/pages/getting-started/preview-changes-locally.mdx @@ -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. - -**Prerequisite**: Please install Node.js (version 18+) before proceeding. - -Follow these steps to install and run the Fern CLI: - -**Step 1**: Install the Fern CLI: - - - -```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 -``` + +Install the following: +- Node.js version 18 or higher +- [The Fern CLI](/learn/cli-api-reference/cli-reference/overview#install-fern-cli) + - +## 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. -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 -### 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. + + +```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 +``` + + + + +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: + + +```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 +``` + + + \ No newline at end of file diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index 3746effc4..0494dbd85 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -183,7 +183,7 @@ Follow this guide to get started with Fern in under 5 minutes. - Before publishing, [preview your changes](/docs/preview-publish/previewing-changes-locally) in your local development environment or generate shareable preview links. + Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links.