From 89e475dcbd6325ee3024dcae6ee4e26caa1dbb6a Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 23 Apr 2026 14:50:37 -0400 Subject: [PATCH 1/3] file organizatoin + readme fix --- README.md | 2 +- docs-starter/.github/CODEOWNERS | 2 - versioning/.github/workflows/check.yml | 20 +++++ versioning/.github/workflows/preview-docs.yml | 80 +++++++++++++++++++ versioning/.github/workflows/publish-docs.yml | 22 +++++ 5 files changed, 123 insertions(+), 3 deletions(-) delete mode 100644 docs-starter/.github/CODEOWNERS create mode 100644 versioning/.github/workflows/check.yml create mode 100644 versioning/.github/workflows/preview-docs.yml create mode 100644 versioning/.github/workflows/publish-docs.yml diff --git a/README.md b/README.md index 0a70f19..8a20ea0 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Example Fern docs projects. Each top-level folder is a self-contained example wi | Example | Description | Live demo | | --- | --- | --- | | [`docs-starter`](./docs-starter) | Minimal starter project | [docs-starter.docs.buildwithfern.com](https://docs-starter.docs.buildwithfern.com) | -| [`docs-versioned`](./docs-versioned) | Versioned site with a version dropdown and a shared page | [versioning.docs.buildwithfern.com](https://versioning.docs.buildwithfern.com) | +| [`versioning`](./docs-versioned) | Versioned site with a version dropdown and a shared page | [versioning.docs.buildwithfern.com](https://versioning.docs.buildwithfern.com) | ## Use an example diff --git a/docs-starter/.github/CODEOWNERS b/docs-starter/.github/CODEOWNERS deleted file mode 100644 index 53a5f4c..0000000 --- a/docs-starter/.github/CODEOWNERS +++ /dev/null @@ -1,2 +0,0 @@ -* @Ryan-Amirthan - diff --git a/versioning/.github/workflows/check.yml b/versioning/.github/workflows/check.yml new file mode 100644 index 0000000..98f4d15 --- /dev/null +++ b/versioning/.github/workflows/check.yml @@ -0,0 +1,20 @@ +name: fern-check + +on: + pull_request: + push: + branches: + - main + +jobs: + run: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Fern CLI + uses: fern-api/setup-fern-cli@v1 + + - name: Check API is valid + run: fern check diff --git a/versioning/.github/workflows/preview-docs.yml b/versioning/.github/workflows/preview-docs.yml new file mode 100644 index 0000000..e4138a9 --- /dev/null +++ b/versioning/.github/workflows/preview-docs.yml @@ -0,0 +1,80 @@ +name: Preview Docs + +on: pull_request + +jobs: + run: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + 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 }} + + - name: Setup Fern CLI + uses: fern-api/setup-fern-cli@v1 + + - name: Generate preview URL + id: generate-docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + HEAD_REF: ${{ github.head_ref }} + run: | + OUTPUT=$(fern generate --docs --preview --id "$HEAD_REF" 2>&1) || true + 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 }} + run: | + PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}" + CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.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<> $GITHUB_OUTPUT + else + echo "page_links=" >> $GITHUB_OUTPUT + fi + + - name: Create comment content + run: | + echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > 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 + + - name: Post PR comment + uses: thollander/actions-comment-pull-request@v2.4.3 + with: + filePath: comment.md + comment_tag: preview-docs + mode: upsert diff --git a/versioning/.github/workflows/publish-docs.yml b/versioning/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..fcc6811 --- /dev/null +++ b/versioning/.github/workflows/publish-docs.yml @@ -0,0 +1,22 @@ +name: publish-docs + +on: + push: + branches: + - main + +jobs: + run: + runs-on: ubuntu-latest + if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }} + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Fern CLI + uses: fern-api/setup-fern-cli@v1 + + - name: Publish Docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: fern generate --docs --log-level debug From fdbc53c0fcfff5713fdc56722288ea9a1d606a7f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 23 Apr 2026 14:53:43 -0400 Subject: [PATCH 2/3] file change --- .../.github => .github}/workflows/check.yml | 0 .../workflows/preview-docs.yml | 0 .../workflows/publish-docs.yml | 0 versioning/.github/workflows/check.yml | 20 ----- versioning/.github/workflows/preview-docs.yml | 80 ------------------- versioning/.github/workflows/publish-docs.yml | 22 ----- 6 files changed, 122 deletions(-) rename {docs-starter/.github => .github}/workflows/check.yml (100%) rename {docs-starter/.github => .github}/workflows/preview-docs.yml (100%) rename {docs-starter/.github => .github}/workflows/publish-docs.yml (100%) delete mode 100644 versioning/.github/workflows/check.yml delete mode 100644 versioning/.github/workflows/preview-docs.yml delete mode 100644 versioning/.github/workflows/publish-docs.yml diff --git a/docs-starter/.github/workflows/check.yml b/.github/workflows/check.yml similarity index 100% rename from docs-starter/.github/workflows/check.yml rename to .github/workflows/check.yml diff --git a/docs-starter/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml similarity index 100% rename from docs-starter/.github/workflows/preview-docs.yml rename to .github/workflows/preview-docs.yml diff --git a/docs-starter/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml similarity index 100% rename from docs-starter/.github/workflows/publish-docs.yml rename to .github/workflows/publish-docs.yml diff --git a/versioning/.github/workflows/check.yml b/versioning/.github/workflows/check.yml deleted file mode 100644 index 98f4d15..0000000 --- a/versioning/.github/workflows/check.yml +++ /dev/null @@ -1,20 +0,0 @@ -name: fern-check - -on: - pull_request: - push: - branches: - - main - -jobs: - run: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Setup Fern CLI - uses: fern-api/setup-fern-cli@v1 - - - name: Check API is valid - run: fern check diff --git a/versioning/.github/workflows/preview-docs.yml b/versioning/.github/workflows/preview-docs.yml deleted file mode 100644 index e4138a9..0000000 --- a/versioning/.github/workflows/preview-docs.yml +++ /dev/null @@ -1,80 +0,0 @@ -name: Preview Docs - -on: pull_request - -jobs: - run: - runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: write - 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 }} - - - name: Setup Fern CLI - uses: fern-api/setup-fern-cli@v1 - - - name: Generate preview URL - id: generate-docs - env: - FERN_TOKEN: ${{ secrets.FERN_TOKEN }} - HEAD_REF: ${{ github.head_ref }} - run: | - OUTPUT=$(fern generate --docs --preview --id "$HEAD_REF" 2>&1) || true - 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 }} - run: | - PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}" - CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.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<> $GITHUB_OUTPUT - else - echo "page_links=" >> $GITHUB_OUTPUT - fi - - - name: Create comment content - run: | - echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > 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 - - - name: Post PR comment - uses: thollander/actions-comment-pull-request@v2.4.3 - with: - filePath: comment.md - comment_tag: preview-docs - mode: upsert diff --git a/versioning/.github/workflows/publish-docs.yml b/versioning/.github/workflows/publish-docs.yml deleted file mode 100644 index fcc6811..0000000 --- a/versioning/.github/workflows/publish-docs.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: publish-docs - -on: - push: - branches: - - main - -jobs: - run: - runs-on: ubuntu-latest - if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }} - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Setup Fern CLI - uses: fern-api/setup-fern-cli@v1 - - - name: Publish Docs - env: - FERN_TOKEN: ${{ secrets.FERN_TOKEN }} - run: fern generate --docs --log-level debug From c16311e3eb319d1f2f4f15f28b77ba6f729367d6 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 23 Apr 2026 14:57:41 -0400 Subject: [PATCH 3/3] update workflows to work with multiple fern folders --- .github/workflows/check.yml | 5 +++++ .github/workflows/preview-docs.yml | 15 ++++++++++----- .github/workflows/publish-docs.yml | 5 +++++ 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 98f4d15..8d5e078 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -9,6 +9,10 @@ on: jobs: run: runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + project: [docs-starter, versioning] steps: - name: Checkout repository uses: actions/checkout@v4 @@ -17,4 +21,5 @@ jobs: uses: fern-api/setup-fern-cli@v1 - name: Check API is valid + working-directory: ${{ matrix.project }} run: fern check diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml index e4138a9..6418886 100644 --- a/.github/workflows/preview-docs.yml +++ b/.github/workflows/preview-docs.yml @@ -8,6 +8,10 @@ jobs: permissions: contents: read pull-requests: write + strategy: + fail-fast: false + matrix: + project: [docs-starter, versioning] steps: - name: Checkout repository uses: actions/checkout@v4 @@ -24,11 +28,12 @@ jobs: - name: Generate preview URL id: generate-docs + working-directory: ${{ matrix.project }} env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} HEAD_REF: ${{ github.head_ref }} run: | - OUTPUT=$(fern generate --docs --preview --id "$HEAD_REF" 2>&1) || true + 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 @@ -40,7 +45,7 @@ jobs: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: | PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}" - CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.mdx' 2>/dev/null || echo "") + 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 @@ -64,8 +69,8 @@ jobs: - name: Create comment content run: | - echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > comment.md - + echo ":herb: **Preview your docs (${{ matrix.project }}):** <${{ steps.generate-docs.outputs.preview_url }}>" > 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 @@ -76,5 +81,5 @@ jobs: uses: thollander/actions-comment-pull-request@v2.4.3 with: filePath: comment.md - comment_tag: preview-docs + comment_tag: preview-docs-${{ matrix.project }} mode: upsert diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index fcc6811..11f752e 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -9,6 +9,10 @@ jobs: run: runs-on: ubuntu-latest if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }} + strategy: + fail-fast: false + matrix: + project: [docs-starter, versioning] steps: - name: Checkout repository uses: actions/checkout@v4 @@ -17,6 +21,7 @@ jobs: uses: fern-api/setup-fern-cli@v1 - name: Publish Docs + working-directory: ${{ matrix.project }} env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs --log-level debug