From 401f2a75a8b44afc8a13cfac30944f25a03e2570 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 22 May 2026 19:19:35 +0000
Subject: [PATCH 1/4] ci: consolidate preview comments into one auto-updating
 comment

- Rewrite preview-docs.yml to use a matrix generate job + a single comment job
- Each matrix job uploads its preview URL as an artifact
- The comment job collects all URLs and posts one consolidated table
- Uses comment_tag + upsert mode to auto-update on each push
- Add graphql example to all workflow matrices (check, preview, publish)

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
---
 .github/workflows/check.yml        |   2 +-
 .github/workflows/preview-docs.yml | 104 +++++++++++++++++------------
 .github/workflows/publish-docs.yml |   2 +-
 3 files changed, 62 insertions(+), 46 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 9d7cbff..01972d4 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
+        project: [docs-starter, graphql, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
index 939aee3..f9e0099 100644
--- a/.github/workflows/preview-docs.yml
+++ b/.github/workflows/preview-docs.yml
@@ -3,25 +3,29 @@ name: Preview Docs
 on: pull_request
 
 jobs:
-  run:
+  generate-preview:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: write
     strategy:
       fail-fast: false
       matrix:
-        project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
+        project:
+          - docs-starter
+          - graphql
+          - i18n
+          - multi-source/homepage
+          - multi-source/seeds
+          - multi-source/seeds-sunflower
+          - multi-source/seeds-tomato
+          - multi-source/greenhouses
+          - multi-source/nursery
+          - versioning
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Fetch full history for git diff
-
-      - 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 }}
+          ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Setup Fern CLI
         uses: fern-api/setup-fern-cli@v1
@@ -37,49 +41,61 @@ jobs:
           echo "$OUTPUT"
           URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
           echo "preview_url=$URL" >> $GITHUB_OUTPUT
-          echo "Preview URL: $URL"
 
-      - name: Get page links for changed MDX files
-        id: page-links
-        env:
-          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+      - name: Save preview URL
+        id: artifact-meta
         run: |
-          PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}"
-          CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '${{ matrix.project }}/**/*.mdx' 2>/dev/null || echo "")
-          
-          if [ -z "$CHANGED_FILES" ] || [ -z "$PREVIEW_URL" ]; then
-            echo "page_links=" >> $GITHUB_OUTPUT; exit 0
-          fi
-          
-          BASE_URL=$(echo "$PREVIEW_URL" | grep -oP 'https?://[^/]+')
-          
-          FILES_PARAM=$(echo "$CHANGED_FILES" | tr '\n' ',' | sed 's/,$//')
-          RESPONSE=$(curl -sf -H "FERN_TOKEN: $FERN_TOKEN" "${PREVIEW_URL}/api/fern-docs/get-slug-for-file?files=${FILES_PARAM}" 2>/dev/null) || {
-            echo "page_links=" >> $GITHUB_OUTPUT; exit 0
-          }
-          
-          PAGE_LINKS=$(echo "$RESPONSE" | jq -r --arg url "$BASE_URL" \
-            '.mappings[] | select(.slug != null) | "- [\(.slug)](\($url)/\(.slug))"')
-          
-          if [ -n "$PAGE_LINKS" ]; then
-            { echo "page_links<<EOF"; echo "$PAGE_LINKS"; echo "EOF"; } >> $GITHUB_OUTPUT
-          else
-            echo "page_links=" >> $GITHUB_OUTPUT
-          fi
+          SAFE_NAME=$(echo "${{ matrix.project }}" | tr '/' '-')
+          echo "safe_name=${SAFE_NAME}" >> $GITHUB_OUTPUT
+          echo "${{ matrix.project }}=${{ steps.generate-docs.outputs.preview_url }}" > "${SAFE_NAME}.txt"
+
+      - name: Upload preview URL
+        uses: actions/upload-artifact@v4
+        with:
+          name: preview-url-${{ steps.artifact-meta.outputs.safe_name }}
+          path: "${{ steps.artifact-meta.outputs.safe_name }}.txt"
+          retention-days: 1
+
+  comment:
+    needs: generate-preview
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Download all preview URLs
+        uses: actions/download-artifact@v4
+        with:
+          pattern: preview-url-*
+          merge-multiple: true
 
-      - name: Create comment content
+      - name: Build comment
         run: |
-          echo ":herb: **Preview your docs (${{ matrix.project }}):** <${{ steps.generate-docs.outputs.preview_url }}>" > comment.md
+          {
+            echo "## :herb: Docs Previews"
+            echo ""
+            echo "| Example | Preview |"
+            echo "| --- | --- |"
+          } > comment.md
 
-          if [ -n "${{ steps.page-links.outputs.page_links }}" ]; then
-            echo "" >> comment.md
-            echo "Here are the markdown pages you've updated:" >> comment.md
-            echo "${{ steps.page-links.outputs.page_links }}" >> comment.md
-          fi
+          for project in docs-starter graphql i18n multi-source/homepage multi-source/seeds multi-source/seeds-sunflower multi-source/seeds-tomato multi-source/greenhouses multi-source/nursery versioning; do
+            SAFE_NAME=$(echo "$project" | tr '/' '-')
+            FILE="${SAFE_NAME}.txt"
+            if [ -f "$FILE" ]; then
+              URL=$(cut -d'=' -f2- "$FILE")
+              if [ -n "$URL" ]; then
+                echo "| \`${project}\` | [Preview](${URL}) |" >> comment.md
+              else
+                echo "| \`${project}\` | :warning: Failed |" >> comment.md
+              fi
+            else
+              echo "| \`${project}\` | :warning: Failed |" >> comment.md
+            fi
+          done
 
       - name: Post PR comment
         uses: thollander/actions-comment-pull-request@v2.4.3
         with:
           filePath: comment.md
-          comment_tag: preview-docs-${{ matrix.project }}
+          comment_tag: preview-docs
           mode: upsert
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index a5588f5..a7895c3 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
+        project: [docs-starter, graphql, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

From a7b907e80cd807cca168d881c4689654c17f8220 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 26 May 2026 15:02:19 +0000
Subject: [PATCH 2/4] ci: rewrite preview workflow to match docs repo pattern

- Single job instead of matrix + consolidation
- Only generate previews for projects with actual file changes
- Use PR number in preview IDs to avoid URL truncation collisions
- Resolve changed MDX files to page slugs via get-slug-for-file API
- Show per-project preview URL with changed page links
- Upgrade to thollander/actions-comment-pull-request@v3

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
---
 .github/workflows/preview-docs.yml | 131 +++++++++++++----------------
 1 file changed, 60 insertions(+), 71 deletions(-)

diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
index f9e0099..dc13a0c 100644
--- a/.github/workflows/preview-docs.yml
+++ b/.github/workflows/preview-docs.yml
@@ -1,101 +1,90 @@
 name: Preview Docs
 
-on: pull_request
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
 
 jobs:
-  generate-preview:
+  preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        project:
-          - docs-starter
-          - graphql
-          - i18n
-          - multi-source/homepage
-          - multi-source/seeds
-          - multi-source/seeds-sunflower
-          - multi-source/seeds-tomato
-          - multi-source/greenhouses
-          - multi-source/nursery
-          - versioning
+      pull-requests: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - 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: Setup Fern CLI
         uses: fern-api/setup-fern-cli@v1
 
-      - name: Generate preview URL
-        id: generate-docs
-        working-directory: ${{ matrix.project }}
+      - name: Generate previews and build comment
         env:
           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
-          HEAD_REF: ${{ github.head_ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
-          OUTPUT=$(fern generate --docs --preview --id "${HEAD_REF}-${{ matrix.project }}" 2>&1) || true
-          echo "$OUTPUT"
-          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
-          echo "preview_url=$URL" >> $GITHUB_OUTPUT
+          PROJECTS="docs-starter graphql i18n multi-source/homepage multi-source/seeds multi-source/seeds-sunflower multi-source/seeds-tomato multi-source/greenhouses multi-source/nursery versioning"
+          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
 
-      - name: Save preview URL
-        id: artifact-meta
-        run: |
-          SAFE_NAME=$(echo "${{ matrix.project }}" | tr '/' '-')
-          echo "safe_name=${SAFE_NAME}" >> $GITHUB_OUTPUT
-          echo "${{ matrix.project }}=${{ steps.generate-docs.outputs.preview_url }}" > "${SAFE_NAME}.txt"
+          : > comment.md
+          HAS_CONTENT=false
 
-      - name: Upload preview URL
-        uses: actions/upload-artifact@v4
-        with:
-          name: preview-url-${{ steps.artifact-meta.outputs.safe_name }}
-          path: "${{ steps.artifact-meta.outputs.safe_name }}.txt"
-          retention-days: 1
+          for project in $PROJECTS; do
+            PROJECT_CHANGES=$(echo "$CHANGED_FILES" | grep "^${project}/" || true)
+            if [ -z "$PROJECT_CHANGES" ]; then
+              continue
+            fi
 
-  comment:
-    needs: generate-preview
-    if: ${{ !cancelled() }}
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - name: Download all preview URLs
-        uses: actions/download-artifact@v4
-        with:
-          pattern: preview-url-*
-          merge-multiple: true
+            SAFE_PROJECT=$(echo "$project" | tr '/' '-')
 
-      - name: Build comment
-        run: |
-          {
-            echo "## :herb: Docs Previews"
-            echo ""
-            echo "| Example | Preview |"
-            echo "| --- | --- |"
-          } > comment.md
+            pushd "$project" > /dev/null
+            OUTPUT=$(fern generate --docs --preview --id "pr${PR_NUMBER}-${SAFE_PROJECT}" 2>&1) || true
+            popd > /dev/null
+            echo "$OUTPUT"
+            URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
+
+            if [ -z "$URL" ]; then
+              continue
+            fi
 
-          for project in docs-starter graphql i18n multi-source/homepage multi-source/seeds multi-source/seeds-sunflower multi-source/seeds-tomato multi-source/greenhouses multi-source/nursery versioning; do
-            SAFE_NAME=$(echo "$project" | tr '/' '-')
-            FILE="${SAFE_NAME}.txt"
-            if [ -f "$FILE" ]; then
-              URL=$(cut -d'=' -f2- "$FILE")
-              if [ -n "$URL" ]; then
-                echo "| \`${project}\` | [Preview](${URL}) |" >> comment.md
-              else
-                echo "| \`${project}\` | :warning: Failed |" >> comment.md
+            BASE_URL=$(echo "$URL" | grep -oP 'https?://[^/]+')
+
+            MDX_CHANGES=$(echo "$PROJECT_CHANGES" | grep '\.mdx$' | sed "s|^${project}/||" || true)
+            PAGE_LINKS=""
+            if [ -n "$MDX_CHANGES" ]; then
+              FILES_PARAM=$(echo "$MDX_CHANGES" | tr '\n' ',' | sed 's/,$//')
+              RESPONSE=$(curl -sf -H "FERN_TOKEN: $FERN_TOKEN" "${URL}/api/fern-docs/get-slug-for-file?files=${FILES_PARAM}" 2>/dev/null) || true
+              if [ -n "$RESPONSE" ]; then
+                PAGE_LINKS=$(echo "$RESPONSE" | jq -r --arg url "$BASE_URL" \
+                  '.mappings[] | select(.slug != null) | "- [\(.slug)](\($url)/\(.slug))"' 2>/dev/null || true)
               fi
-            else
-              echo "| \`${project}\` | :warning: Failed |" >> comment.md
             fi
+
+            echo ":herb: **Preview \`${project}\`:** <${URL}>" >> comment.md
+            if [ -n "$PAGE_LINKS" ]; then
+              echo "" >> comment.md
+              echo "Here are the markdown pages you've updated:" >> comment.md
+              echo "$PAGE_LINKS" >> comment.md
+            fi
+            echo "" >> comment.md
+            HAS_CONTENT=true
           done
 
+          if [ "$HAS_CONTENT" = false ]; then
+            echo ":herb: No docs changes detected in this PR." > comment.md
+          fi
+
       - name: Post PR comment
-        uses: thollander/actions-comment-pull-request@v2.4.3
+        uses: thollander/actions-comment-pull-request@v3
         with:
-          filePath: comment.md
-          comment_tag: preview-docs
+          file-path: comment.md
+          comment-tag: preview-docs
           mode: upsert

From edea9708b48070b7ea13a01e23e50347aee7d574 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 26 May 2026 15:06:47 +0000
Subject: [PATCH 3/4] test: add minor text change to trigger preview

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
---
 docs-starter/fern/docs/pages/welcome.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs-starter/fern/docs/pages/welcome.mdx b/docs-starter/fern/docs/pages/welcome.mdx
index 8e965b2..21d441a 100644
--- a/docs-starter/fern/docs/pages/welcome.mdx
+++ b/docs-starter/fern/docs/pages/welcome.mdx
@@ -4,7 +4,7 @@ subtitle: Everything you need to build the best developer experience
 slug: welcome
 ---
 
-This repository is a starter template for building documentation with [Fern](https://buildwithfern.com). It includes a sample Plant Store API to demonstrate how Fern generates interactive API reference documentation from an OpenAPI specification.
+This repository is a starter template for building documentation with [Fern](https://buildwithfern.com). It includes a sample Plant Store API to demonstrate how Fern generates interactive API reference documentation from an OpenAPI specification. Get started in minutes.
 
 Use this template to get started quickly, then replace the sample content with your own API and documentation.
 

From f50a0076407c649708da510eb8bd42a4ef65eac6 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 26 May 2026 15:08:13 +0000
Subject: [PATCH 4/4] Revert "test: add minor text change to trigger preview"

This reverts commit edea9708b48070b7ea13a01e23e50347aee7d574.
---
 docs-starter/fern/docs/pages/welcome.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs-starter/fern/docs/pages/welcome.mdx b/docs-starter/fern/docs/pages/welcome.mdx
index 21d441a..8e965b2 100644
--- a/docs-starter/fern/docs/pages/welcome.mdx
+++ b/docs-starter/fern/docs/pages/welcome.mdx
@@ -4,7 +4,7 @@ subtitle: Everything you need to build the best developer experience
 slug: welcome
 ---
 
-This repository is a starter template for building documentation with [Fern](https://buildwithfern.com). It includes a sample Plant Store API to demonstrate how Fern generates interactive API reference documentation from an OpenAPI specification. Get started in minutes.
+This repository is a starter template for building documentation with [Fern](https://buildwithfern.com). It includes a sample Plant Store API to demonstrate how Fern generates interactive API reference documentation from an OpenAPI specification.
 
 Use this template to get started quickly, then replace the sample content with your own API and documentation.