Move to mystmd based build (#19)

* MNT: move to complete static page without blog based on mystmd
* remove project pages, link instead to minimize maintenance cost
* updates according #17, #18, #20

.github/workflows/build-book.yaml

@@ -0,0 +1,55 @@
+name: build-book
+
+on:
+  workflow_call:
+
+jobs:
+  build-book:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mystmd
+      - name: Build the book pullrequest
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_URL: /${{ github.event.repository.name }}/_preview/${{ github.event.pull_request.number }}
+        run: |
+          # build the book
+          myst build --ci --html
+      - name: Build the book push
+        if: github.event_name == 'push'
+        env:
+          BASE_URL: /${{ github.event.repository.name }}
+        run: |
+          # build the book 
+          myst build --ci --html
+      - name: Zip the book
+        run: |
+          set -x
+          set -e
+          if [ -f book.zip ]; then
+              rm -rf book.zip
+          fi
+          zip -r book.zip _build/html
+      - name: Upload zipped book artifact pullrequest
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: book-zip-${{github.event.number}}
+          path: ./book.zip
+      - name: Upload zipped book artifact push
+        if: github.event_name == 'push'
+        uses: actions/upload-artifact@v4
+        with:
+          name: book-zip
+          path: ./book.zip

.github/workflows/delete-preview.yaml

@@ -0,0 +1,24 @@
+name: delete-preview
+
+on:
+  workflow_call:
+
+jobs:
+  delete:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview files
+        run: |
+          rm -rf _preview/${{ github.event.pull_request.number }}
+      - name: Commit the changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          branch: gh-pages
+          commit_message: Delete preview for pull request \#${{ github.event.pull_request.number }}

.github/workflows/deploy-book.yaml

@@ -0,0 +1,85 @@
+name: deploy-book
+
+on:
+  workflow_call:
+    inputs:
+      artifact_name:
+        description: 'Name of the artifact (zipped book) created by previous build step'
+        required: false
+        default: book-zip
+        type: string
+      destination_dir:
+        description: 'Path to publish to on GitHub Pages, relative to site root. We use this to deploy previews in a subdirectory.'
+        required: false
+        default: ''
+        type: string
+      is_preview:
+        description: 'Are we deploying a preview?'
+        required: false
+        default: 'false'
+        type: string
+      cname:
+        description: 'Custom domain name'
+        required: false
+        default: 'None'  # This is just a flag for whether to ignore this input
+        type: string
+      publish_dir:
+        description: 'Publish dir for the peaceiris/actions-gh-pages action'
+        required: false
+        default: '_build/html'
+        type: string
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps: 
+      - name: Download merged artifact
+        if: inputs.is_preview != 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact_name }}
+
+      # For the preview, the official download-artifact action doesn't work
+      # because the artifact is created by a different workflow
+      - name: Download preview artifact
+        if: inputs.is_preview == 'true'
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workflow: build-book.yaml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: ${{ inputs.artifact_name }}
+
+      - name: Unzip the book
+        run: |
+          rm -rf _build/html
+          unzip book.zip
+          rm -f book.zip
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/[email protected]
+        if: |
+          (github.ref == 'refs/heads/main'
+          && inputs.cname == 'None')
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ inputs.publish_dir }}
+          enable_jekyll: false
+          keep_files: true  # This preserves existing previews from open PRs
+          destination_dir: ${{ inputs.destination_dir }}
+
+      - name: Deploy to GitHub Pages with custom domain
+        uses: peaceiris/[email protected]
+        if: |
+          (github.ref == 'refs/heads/main'
+          && inputs.cname != 'None')
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ inputs.publish_dir }}
+          enable_jekyll: false
+          keep_files: true  # This preserves existing previews from open PRs
+          destination_dir: ${{ inputs.destination_dir }}
+          cname: ${{ inputs.cname }}

.github/workflows/deploy-preview.yaml

@@ -0,0 +1,137 @@
+name: deploy-preview
+on:
+  workflow_run:
+    workflows:
+      - trigger-book-build
+    types:
+      - requested
+      - completed
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch Repo Name
+        id: repo-name
+        run: echo "::set-output name=value::$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')"  # just the repo name, not owner
+
+      - name: Set message value
+        run: |
+          echo "comment_message=👋 Thanks for opening this PR! The Cookbook will be automatically built with [GitHub Actions](https://github.com/features/actions). To see the status of your deployment, click below." >> $GITHUB_ENV
+
+      - name: Find Pull Request
+        uses: actions/github-script@v7
+        id: find-pull-request
+        with:
+          script: |
+            let pullRequestNumber = ''
+            let pullRequestHeadSHA = ''
+            core.info('Finding pull request...')
+            const pullRequests = await github.rest.pulls.list({owner: context.repo.owner, repo: context.repo.repo})
+            for (let pullRequest of pullRequests.data) {
+              if(pullRequest.head.sha === context.payload.workflow_run.head_commit.id) {
+                  pullRequestHeadSHA = pullRequest.head.sha
+                  pullRequestNumber = pullRequest.number
+                  break
+              }
+            }
+            core.setOutput('number', pullRequestNumber)
+            core.setOutput('sha', pullRequestHeadSHA)
+            if(pullRequestNumber === '') {
+              core.info(
+                 `No pull request associated with git commit SHA: ${context.payload.workflow_run.head_commit.id}`
+              )
+            }
+            else{
+              core.info(`Found pull request ${pullRequestNumber}, with head sha: ${pullRequestHeadSHA}`)
+            }
+
+      - name: Find preview comment
+        uses: peter-evans/find-comment@v3
+        if: steps.find-pull-request.outputs.number != ''
+        id: fc
+        with:
+          issue-number: '${{ steps.find-pull-request.outputs.number }}'
+          comment-author: 'github-actions[bot]'
+          body-includes: '${{ env.comment_message }}'
+
+      - name: Create preview comment
+        if: |
+          github.event.workflow_run.conclusion != 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id == ''
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ steps.find-pull-request.outputs.number }}
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: In Progress
+
+      - name: Update preview comment
+        if: |
+          github.event.workflow_run.conclusion != 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: In Progress
+
+      - name: Download Artifact Book
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workflow: build-book.yaml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: book-zip-${{ steps.find-pull-request.outputs.number }}
+
+      - name: Unzip the book
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        run: |
+          rm -rf _build/html
+          unzip book.zip
+          rm -f book.zip
+
+      # Push the book's HTML to github-pages
+      # This will be published at /_preview/PRnumber/ relative to the main site
+      - name: Deploy to GitHub pages
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/html
+          enable_jekyll: false
+          destination_dir: _preview/${{ steps.find-pull-request.outputs.number }}
+
+      - name: Finalize preview comment
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: https://${{ github.repository_owner }}.github.io/${{ steps.repo-name.outputs.value }}/_preview/${{ steps.find-pull-request.outputs.number }}

.github/workflows/find-pull-request.yaml

@@ -0,0 +1,25 @@
+name: find-pull-request
+
+on:
+  workflow_call:
+    outputs:
+      number:
+        description: "The Pull Request number"
+        value: ${{ jobs.find-pr.outputs.number }}
+      sha:
+        description: "The SHA of the commit associated with this PR"
+        value: ${{ jobs.find-pr.outputs.sha }}
+
+jobs:
+  find-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      number: ${{ steps.find-pull-request.outputs.pullRequestNumber }}
+      sha: ${{ steps.find-pull-request.outputs.mergeCommitSha }}
+    steps:
+      - name: Find Pull Request
+        id: find-pull-request
+        uses: potiuk/get-workflow-origin@v1_1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          sourceRunId: ${{ github.event.workflow_run.id }}

.github/workflows/link-checker.yaml

@@ -0,0 +1,25 @@
+name: link-checker
+
+on:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  link-checker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mystmd
+      - name: Check external links
+        run: |
+          myst build --ci --check-links --strict