Merge pull request #39 from TeachBooks/wip/redirects

Redirects & archived branches

.github/workflows/deploy-book.yml

@@ -11,24 +11,40 @@ on:
 # https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  # Branch published on root (eg. teachbooks.github.io/template/).
-  # `main` as primary by default, advised to make it `published` to start using draft-publish-workflow
+
+  # Branch shown on root (eg. teachbooks.github.io/template/).
+  # `main` as primary by default, advised to use branch with most recent content.
   PRIMARY_BRANCH: ${{ vars.PRIMARY_BRANCH != '' && vars.PRIMARY_BRANCH || 'main' }}
+
+  # If to copy the PRIMARY_BRANCH to root ('copy') or redirect from root to the PRIMARY_BRANCH ('redirect')
+  # By default, redirects to PRIMARY_BRANCH ('redirect')
+  # Advised to use redirect if you expect to archive a version in the future so that the URL doesn't change for the reader
+  BEHAVIOR_PRIMARY: ${{ vars.BEHAVIOR_PRIMARY != '' && vars.BEHAVIOR_PRIMARY || 'redirect' }}
+
   # Publish branch to custom url with an alias
   # Space-separated list of branch names, e.g. 'draft:main'
   # By default, no aliases are defined (''). 
   # If no alias is wanted, BRANCH_ALIASES may be set to ' ' (space).
   BRANCH_ALIASES: ${{ vars.BRANCH_ALIASES }}
+
   # Which branches to publish
   # Space-separated list of branch names, e.g. 'main second third'.
   # By default, deploy all branches. This is indicated by '*'.
   BRANCHES_TO_DEPLOY: ${{ vars.BRANCHES_TO_DEPLOY != '' && vars.BRANCHES_TO_DEPLOY || '*' }}
+
   # Preprocessing is described here: (as described here: https://teachbooks.github.io/TeachBooks/cli/cli.html#cmdoption-teachbooks-build-publish)
   # Space-separated list of branch names, e.g. 'main second third'.
   # By default, preprocess no branches ('').
   # Preprocessing no branches can also be set by ' '.
   BRANCHES_TO_PREPROCESS: ${{ vars.BRANCHES_TO_PREPROCESS }}
 
+  # Add banner to published branch: You are viewing an archived version of the book. Click here (link to root) for the latest version.
+  # Space-separated list of branch names, e.g. 'main second third'.
+  # By default, archives no branches (' ')
+  # Note: does not support '*'
+  BRANCHES_ARCHIVED: ${{ vars.BRANCHES_ARCHIVED }}
+
+
 jobs:
   get-branches:
     runs-on: ubuntu-latest
@@ -112,17 +128,23 @@ jobs:
         ref: ${{ matrix.branch }}
         submodules: 'true'
 
-    - name: Record if branch is preprocessed for cache
+    - name: Record extra cache info
       run: |
+        # Record filenames listing -- this updates the cache on filename change
+        find book/ -type f >> EXTRA_CACHE_VARS.txt
+        # Record if branch is preprocessed
         if [ "$BRANCHES_TO_PREPROCESS" == "*" ] || echo "$BRANCHES_TO_PREPROCESS" | tr ' ' '\n' | grep "^${{ matrix.branch }}$"; then
-          echo true > EXTRA_CACHE_VARS.txt
+          echo true >> EXTRA_CACHE_VARS.txt
         else
-          echo false > EXTRA_CACHE_VARS.txt
+          echo false >> EXTRA_CACHE_VARS.txt
         fi
-
-    - name: Record filenames for cache
-      run: |
-         find book/ -type f >> EXTRA_CACHE_VARS.txt
+        # Record if branch is archived
+        if echo "$BRANCHES_ARCHIVED" | tr ' ' '\n' | grep "^${{ matrix.branch }}$"; then
+          echo true >> EXTRA_CACHE_VARS.txt
+        else
+          echo false >> EXTRA_CACHE_VARS.txt
+        fi
+        cat EXTRA_CACHE_VARS.txt
 
     - name: Cache page build
       id: cache-html
@@ -138,7 +160,9 @@ jobs:
       with:
         python-version: 3.11
 
-    - run: |
+    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
+      name: Record current date for cache
+      run: |
         echo "WEEK=$(date +%V)" >> $GITHUB_ENV
 
     - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
@@ -157,6 +181,18 @@ jobs:
         echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
         echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
 
+    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
+      name: Insert banner if archived
+      run: |
+        if echo "$BRANCHES_ARCHIVED" | tr ' ' '\n' | grep "^${{ matrix.branch }}$"; then
+          {
+            url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')
+            echo 'html:'
+            echo "  announcement: 'You are viewing an archived version of the book. Click <a href=\"$url$PRIMARY_BRANCH\">here</a> for the latest version.'"
+          } >> book/_config.yml
+          cat book/_config.yml
+        fi
+
     - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
       name: Preprocess & build the book from branch
       run: |
@@ -255,6 +291,8 @@ jobs:
     permissions:
       pages: write
       id-token: write
+    env:
+      BRANCHES: ${{ needs.get-branches.outputs.branches }}
     steps:
     - uses: actions/checkout@v4
 
@@ -285,6 +323,7 @@ jobs:
 
     - name: Copy primary book to root, fail if names conflict
       timeout-minutes: 1
+      if: ${{ env.BEHAVIOR_PRIMARY == 'copy' }}
       run: |
         GLOBIGNORE=".:.."
         # -i leads to a prompt in case of conflict, => a timeout
@@ -328,7 +367,11 @@ jobs:
 
           echo
           echo '#### Primary book at root'
-          echo "The book at the website root <$url> is from the primary branch \\\`$PRIMARY_BRANCH\\\`."
+          if [ ${{ env.BEHAVIOR_PRIMARY  }} == 'copy' ]; then
+            echo "The book at the website root <$url> is from the primary branch \\\`$PRIMARY_BRANCH\\\`."
+          elif [ ${{ env.BEHAVIOR_PRIMARY  }} == 'redirect' ]; then
+            echo "The book at the website root <$url> redirects to the primary branch \\\`$PRIMARY_BRANCH\\\`."
+          fi
           echo "Status: $primary_status"
         } >> summary.md
 
@@ -382,6 +425,38 @@ jobs:
           echo "No build errors or warnings encountered." >> summary.md
         fi
 
+    - name: Add a custom 404 to redirect
+      env:
+        # https:(0)/(1)/uname.github.io(2)/rname(3)/bname(4) */
+        # if urlParts.len < 4, bname is undefined */
+        HTML_TEMPLATE_404_REDIRECT: |
+          <!DOCTYPE html><title>Redirecting...</title>
+          <body></body>
+          <script>
+          let currentUrl = window.location.href;
+          let urlParts = currentUrl.split('/');
+          console.log("urlParts before", urlParts);
+          let bname = urlParts[4];
+          console.log("bname", bname);
+          let branches = $BRANCHES;
+          console.log("branches", branches);
+          if (!branches.includes(bname)) {
+              urlParts.splice(4, 0, '$PRIMARY_BRANCH');
+              console.log("urlParts after", urlParts);
+              let newUrl = urlParts.join('/');
+              window.location.href = newUrl;
+          } else {
+              document.title = "Page Not Found";
+              document.body.innerHTML = "<h1>Page Not Found</h1>";
+          }
+          </script>
+        # HTML_TEMPLATE_404_TRUE: |
+        #   <!DOCTYPE html><title>404 Not Found</title>
+        #   404 Not Found
+      run: |
+        # echo "$HTML_TEMPLATE_404_TRUE" > final/404-not-found.html
+        echo "$HTML_TEMPLATE_404_REDIRECT" | envsubst | tee final/404.html
+
     - name: Upload final Pages artifact
       uses: actions/upload-pages-artifact@v3
       with:
@@ -436,9 +511,11 @@ jobs:
           echo "Variables can be set at ${{ format('{0}/{1}/settings/variables/actions', github.server_url, github.repository) }}"
           echo '```'
           echo "PRIMARY_BRANCH=$PRIMARY_BRANCH $(isdefault ${{ vars.PRIMARY_BRANCH }})"
+          echo "BEHAVIOR_PRIMARY=$BEHAVIOR_PRIMARY $(isdefault ${{vars.BRANCHES_TO_PREPROCESS}})"
           echo "BRANCH_ALIASES=$BRANCH_ALIASES $(isdefault ${{ vars.BRANCH_ALIASES }})"
           echo "BRANCHES_TO_DEPLOY=$BRANCHES_TO_DEPLOY $(isdefault ${{ vars.BRANCHES_TO_DEPLOY }})"
           echo "BRANCHES_TO_PREPROCESS=$BRANCHES_TO_PREPROCESS $(isdefault ${{ vars.BRANCHES_TO_PREPROCESS }})"
+          echo "BRANCHES_ARCHIVED=$BRANCHES_ARCHIVED $(isdefault ${{ vars.BRANCHES_ARCHIVED }})"
           echo '```'
         } >> $GITHUB_STEP_SUMMARY
 

404.html

@@ -0,0 +1,2 @@
+<!DOCTYPE html><title>404</title>
+hello html!

404.md

@@ -0,0 +1,4 @@
+---
+permalink: /404.html
+---
+hello world.

README.md

@@ -13,6 +13,7 @@ It has the following features:
 - Optionally preprocess branches using the [`teachbooks` package](https://github.com/TeachBooks/TeachBooks).
 - Converting branch-names to well-defined URLs
 - Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these setting are ill-defined or conflicting. Although aliases are not allowed by GitHub Pages, it seems you can use one alias, but not more.
+- Redirects the root directory to one of the branches or copy one of the brnaches to root.
 
 The [TeachBooks template book](https://github.com/TeachBooks/template) uses this functionality for example: The workflow `call-deploy-book.yml` calls the `deploy-book.yml` workflow, which builds the Jupyter books at the calling repository for all branches, and deploys them via GitHub Pages.
 
@@ -29,19 +30,25 @@ This workflow is used in `TeachBooks/template`. Feel free to juse it for your Te
 
 You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
 - `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
-  - This sets the branch which is hosted on root.
-  - It is advised to make it `published` to start using draft-publish-workflow
+  - This sets the branch which is shown on root.
+  - It is advised to show your most recent branch on root.
+- `BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
+  - This indicates whether to copy the PRIMARY_BRANCH to root ('copy') or redirect from root to the PRIMARY_BRANCH ('redirect')
+  - Advised to use redirect if you expect to archive a version in the future so that the URL doesn't change for the reader.
 - `BRANCH_ALIASES` which is set to ` `(space) whenever it's not defined in the repository variables.
-  - This defines an alias for a branch
-  - It should be an alias-rule, e.g. 'alias:really-long-branch-name`
+  - This defines an alias (custom URL) for a branch
+  - Variable should be an Space-separated list of branch names, e.g. 'alias:really-long-branch-name`
   - If no alias is wanted, `BRANCH_ALIASES` may be set to ' ' (space).
 - `BRANCHES_TO_DEPLOY`  which is set to `*` (all branches) whenever it's not defined in the repository variables.
   - This defines the branches to deploy.
   - It should be a space-separated list of branch names, e.g. 'main second third'.
 - `BRANCHES_TO_PREPROCESS` which is to to ` ` (space, no branch) whenever it's not defined in the repository variables
-  - This defines the branches to preprocess with the `TeachBooks` package, this removed book-pages defined with `# START REMOVE FROM PUBLISH` and `# END REMOVE FROM PUBLISH`
+  - This defines the branches to preprocess with the [`TeachBooks` package](https://teachbooks.github.io/TeachBooks/cli/cli.html#cmdoption-teachbooks-build-publish), which removed book-pages and config lines defined with `# START REMOVE FROM PUBLISH` and `# END REMOVE FROM PUBLISH`
   - It should be a space-separated list of branch names, e.g. 'main second third'.
   - If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
+- `BRANCHES_ARCHIVED` which is set to ` ` (space, no branch) whenever it's not defined in the repository varibles
+  - This adds a banner to the published branch: You are viewing an archived version of the book. Click here for the latest version.
+  - It should be a space-separate list of branch names, e.g. 'main second third'.
 
 In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch trigger the workflow. You can limit the branches or subdirectories.
 
@@ -70,7 +77,7 @@ Here's an example for a summary for the template book:
 > ⭕ `Build failed [2]` - build failure, no previous version reused.
 >
 > #### Primary book at root
-> The book at the website root <https://teachbooks.github.io/testable-template/> is from the primary branch `main` (status: `Published`).
+> The book at the website root <https://teachbooks.github.io/testable-template/> redirects to the primary branch `main` (status: ✅ `Published`).
 > 
 > ### Aliases
 > | Alias ➡️ | Target 🎯 | Link 🔗 |  Build status ☑️ |
@@ -98,4 +105,6 @@ Here's an example for a summary for the template book:
 > BRANCH_ALIASES=draft:main
 > BRANCHES_TO_DEPLOY=* (default value used)
 > BRANCHES_TO_PREPROCESS=main
+> BEHAVIOR_PRIMARY=redirect (default value used)
+> BRANCHES_ARCHIVED= (default value used)
 > ```