Merge branch 'main' into worktree-screenshot-tool

# Conflicts:
#	docs/websites/images/navbar-tools-dark.png
#	docs/websites/images/navbar-tools.png
#	docs/websites/website-navigation.qmd

Author: cderv

.github/workflows/actions/release-info/action.yml

@@ -27,5 +27,5 @@ inputs:
     required: true
 
 runs:
-  using: "node20"
+  using: "node24"
   main: "index.js"

.github/workflows/optimize-images.yml

@@ -0,0 +1,64 @@
+name: Optimize Images
+
+on:
+  push:
+    branches: [main, prerelease]
+    paths:
+      - '**/*.png'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  OXIPNG_VERSION: "10.1.0"
+
+jobs:
+  optimize-png:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Install oxipng
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/oxipng"
+          gh release download "v${OXIPNG_VERSION}" \
+            --repo oxipng/oxipng \
+            --pattern "*x86_64-unknown-linux-musl.tar.gz" \
+            --output - | tar xz --strip-components=1 -C "$RUNNER_TEMP/oxipng"
+
+      - name: Get changed PNG files
+        id: changed-pngs
+        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
+        with:
+          files: '**/*.png'
+          separator: '\n'
+
+      - name: Optimize PNGs
+        if: steps.changed-pngs.outputs.any_changed == 'true'
+        env:
+          ALL_CHANGED_FILES: ${{ steps.changed-pngs.outputs.all_changed_files }}
+        run: |
+          echo "$ALL_CHANGED_FILES" | while IFS= read -r file; do
+            if [ -f "$file" ]; then
+              echo "Optimizing: $file"
+              "$RUNNER_TEMP/oxipng/oxipng" -o 4 -i 0 --strip safe "$file"
+            fi
+          done
+
+      - name: Commit optimized images
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7
+        with:
+          commit_message: "Optimize PNG images with oxipng"
+          commit_user_name: github-actions[bot]
+          commit_user_email: 41898282+github-actions[bot]@users.noreply.github.com
+          commit_author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
+          file_pattern: '**/*.png'

.github/workflows/port-to-prerelease.yml

@@ -27,12 +27,12 @@ jobs:
         startsWith(github.event.comment.body, '/sync-prerelease')
       )
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Create backport pull requests
         id: synced-pr
-        # https://github.com/korthout/backport-action/releases/tag/v3.0.0
-        uses: korthout/backport-action@7e7cb1977d64d20339e8fdec12c0a1a065371de7
+        # https://github.com/korthout/backport-action/releases/tag/v4.2.0
+        uses: korthout/backport-action@4aaf0e03a94ff0a619c9a511b61aeb42adea5b02
         with:
           cherry_picking: auto
           branch_name: sync-${pull_number}-to-${target_branch}
@@ -52,7 +52,7 @@ jobs:
 
       - name: Trigger deploy using a comment
         if: steps.synced-pr.outputs.was_successful == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           # special fine-grained token for issue comment trigger
           github-token: ${{ secrets.ISSUE_COMMENT_TRIGGER_PAT }}

.github/workflows/preview.yml

@@ -1,6 +1,8 @@
 on:
   pull_request:
     branches: [main, prerelease]
+    paths-ignore:
+      - '.github/**'
   issue_comment:
     types: [created]
 
@@ -63,10 +65,24 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
-        with: 
+        uses: actions/checkout@v6
+        with:
           ref: refs/pull/${{ github.event.pull_request.number || github.event.issue.number }}/merge
 
+      # On issue_comment events (e.g. /deploy-preview), github.event.pull_request
+      # is not populated so tj-actions/changed-files can't determine the base commit
+      # to diff against. Fetch it from the API so we can pass it explicitly.
+      - name: Get PR base SHA
+        if: github.event_name != 'pull_request'
+        id: pr-info
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pr_number=${{ github.event.issue.number }}
+          base_sha=$(gh -R $GITHUB_REPOSITORY pr view $pr_number --json baseRefOid --jq '.baseRefOid')
+          echo "base_sha=$base_sha" >> "$GITHUB_OUTPUT"
+        shell: bash
+
       - name: Get latest pre-release from github
         id: github-release
         env: 
@@ -127,20 +143,23 @@ jobs:
 
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v46.0.5
+        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
         with:
+          base_sha: ${{ github.event.pull_request.base.sha || steps.pr-info.outputs.base_sha }}
           files: |
             # don't consider modifications on file used for includes for now.
             license.md
             docs/**/[^_]*.qmd
             docs/**/[^_]*.md
             docs/extensions/listings/*.yml
+            docs/reference/**/*.json
+            docs/cli/*.json
           json: true
           escape_json: false
 
       - name: Create custom PR comment
         if: github.event.pull_request || github.event.issue.pull_request
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         env:
           DEPLOY_URL: ${{ steps.netlify-deploy.outputs.deploy-url }}
           CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
@@ -149,40 +168,76 @@ jobs:
           script: |
             const prNumber = context.payload.pull_request?.number || context.payload.issue.number;
             const deployUrl = process.env.DEPLOY_URL;
-            const changedFiles = JSON.parse(process.env.CHANGED_FILES);
-            
+            const changedFiles = JSON.parse(process.env.CHANGED_FILES || '[]');
+
             let commentBody = `## 📝 Preview Deployment\n\n`;
             commentBody += `🔍 Full site preview: [${deployUrl}](${deployUrl})\n\n`;
-            
+
             if (changedFiles.length > 0) {
-              commentBody += `### 🔄 Modified Documents\n\n`;
+              // Explicit mapping for files that don't follow standard naming conventions
+              const specialFileMapping = {
+                'docs/extensions/listings/shortcodes-and-filters.yml': 'docs/extensions/index.html',
+                'docs/extensions/listings/journal-articles.yml': 'docs/extensions/index.html',
+                'docs/extensions/listings/custom-formats.yml': 'docs/extensions/index.html',
+                'docs/extensions/listings/revealjs-formats.yml': 'docs/extensions/index.html',
+                'docs/extensions/listings/revealjs.yml': 'docs/extensions/index.html',
+                'docs/cli/cli-info.json': 'docs/reference/index.html',
+              };
+
+              // Projects/ JSON files have many-to-one mapping to .qmd pages
+              const projectsJsonMapping = {
+                'book': 'docs/reference/projects/books.html',
+                'manuscript': 'docs/reference/projects/manuscripts.html',
+                'project': 'docs/reference/projects/options.html',
+                'preview': 'docs/reference/projects/options.html',
+                'serve': 'docs/reference/projects/options.html',
+              };
+              const projectsDefault = 'docs/reference/projects/websites.html';
+
+              // Resolve each changed file to its preview URL path
+              // Group files by their target page for deduplication
+              const pageToFiles = new Map();
+
               changedFiles.forEach(file => {
                 let fileUrlPath;
 
-                // Define a mapping for special files to their corresponding URLs
-                const specialFileMapping = {
-                  'docs/extensions/listings/shortcodes-and-filters.yml': 'docs/extensions/index.html',
-                  'docs/extensions/listings/journal-articles.yml': 'docs/extensions/index.html',
-                  'docs/extensions/listings/custom-formats.yml': 'docs/extensions/index.html',
-                  'docs/extensions/listings/revealjs-formats.yml': 'docs/extensions/index.html',
-                  'docs/extensions/listings/revealjs.yml': 'docs/extensions/index.html'
-                };
-
-                // Check if the file is in the special mapping
                 if (specialFileMapping[file]) {
                   fileUrlPath = specialFileMapping[file];
                 } else if (file.endsWith('.qmd') || file.endsWith('.md')) {
-                  // Convert path to URL (removing file extension and adding appropriate path)
                   fileUrlPath = file.replace(/\.(qmd|md)$/, '.html');
+                } else if (file.startsWith('docs/reference/projects/') && file.endsWith('.json')) {
+                  const stem = file.split('/').pop().replace('.json', '');
+                  fileUrlPath = projectsJsonMapping[stem] || projectsDefault;
+                } else if (file.endsWith('.json')) {
+                  // Generic: formats/, cells/, metadata/ JSON have sibling .qmd files
+                  fileUrlPath = file.replace(/\.json$/, '.html');
                 }
 
                 if (fileUrlPath) {
-                  const fileUrl = `${deployUrl}/${fileUrlPath}`;
-                  commentBody += `- [${file}](${fileUrl})\n`;
+                  if (!pageToFiles.has(fileUrlPath)) {
+                    pageToFiles.set(fileUrlPath, []);
+                  }
+                  pageToFiles.get(fileUrlPath).push(file);
                 }
               });
+
+              if (pageToFiles.size > 0) {
+                commentBody += `### 🔄 Modified Documents\n\n`;
+                for (const [page, files] of pageToFiles) {
+                  const fileUrl = `${deployUrl}/${page}`;
+                  if (files.length === 1) {
+                    commentBody += `- [${page}](${fileUrl})\n`;
+                  } else {
+                    // Multiple source files map to one page - show page with file summary
+                    const basenames = files.map(f => f.split('/').pop());
+                    const shown = basenames.slice(0, 3).join(', ');
+                    const rest = basenames.length > 3 ? `, +${basenames.length - 3} more` : '';
+                    commentBody += `- [${page}](${fileUrl}) (${shown}${rest})\n`;
+                  }
+                }
+              }
             }
-            
+
             github.rest.issues.createComment({
               issue_number: prNumber,
               owner: context.repo.owner,

.github/workflows/publish.yml

@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           # if called from workflow_call event, checkout the ref otherwise use default
           ref: ${{ inputs.ref || '' }}

.github/workflows/test-algolia-upload.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:

.github/workflows/update-downloads.yml

@@ -14,7 +14,7 @@ jobs:
       prerelease_version: ${{ steps.get-versions.outputs.prerelease_version }}
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 #        with:
 #          token: ${{ secrets.COMMIT_PAT }}
 
@@ -38,13 +38,12 @@ jobs:
 
       - name: Commit Changes to main branch
         id: auto-commit
-        uses: stefanzweifel/git-auto-commit-action@v5
+        uses: stefanzweifel/git-auto-commit-action@v7
         with:
           repository: .
           commit_user_name: Github Action Runner
           commit_user_email: runner@quarto.org
           commit_author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
-          skip_checkout: true
 
       - name: Cherry-pick change to prerelease branch
         id: cherry-pick-prerelease