Larger Build/GH Actions Thoughts

[Prospero23]

I believe in our GitHub Actions build workflows for all the web repos we could update all our core actions (actions-gh-pages, checkout, and setup-node) to their newest major versions without breaking anything.

Updating Build Step of this Repo

I am starting to do some brainstorming about the best way to bring in the builds from examples, docs, and playground. I think a pretty trivial solution could be to do something like the following (keeping the versions we are using now for simplicity):

name: Build Parent Eleventy

on:
  push:  # runs on push
  workflow_dispatch: # can run manually
  repository_dispatch: # can be run from other repos
    types: [sync]  # only runs when type is sync

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout vexflow.github.io
        uses: actions/checkout@v3

      - name: Checkout vexflow docs gh_pages
        uses: actions/checkout@v3
        with:
          repository: vexflow/vexflow-docs   # repo to checkout
          ref: gh_pages # branch to checkout
          path: src/docs # where to place it

      - name: Checkout vexflow examples gh_pages
        uses: actions/checkout@v3
        with:
          repository: vexflow/vexflow-examples
          ref: gh_pages
          path: src/examples

      - name: Checkout vexflow sandbox gh_pages
        uses: actions/checkout@v3
        with:
          repository: vexflow/vexflow-sandbox
          ref: gh_pages
          path: src/sandbox

      - name: Use Node.js current
        uses: actions/setup-node@v3
        with:
          node-version: current

      - name: Install dependencies & build
        run: |
          npm ci
          npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3.8.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # publish_dir is the folder where Eleventy outputs the built site
          publish_dir: _site
          # publish_branch is the GitHub Pages target branch
          publish_branch: gh-pages

This would just pull in the three other repos and store them under src/repo-name. Using repository_dispatch could set us up to be able to call this build step to automatically rebuild this site whenever one of the child repos is rebuilt.

Eleventy Setup

We could add the following lines to the eleventy config to serve the files from this domain:

eleventyConfig.addPassthroughCopy("src/docs");
eleventyConfig.addPassthroughCopy("src/examples");
eleventyConfig.addPassthroughCopy("src/sandbox");

What this would change

This approach would cause the pages in those repos to not be seen as templates by 11ty. Meaning if we want to have a navbar on each page, I believe we would have to add it as a transform. It seems that transforms work better with plain html than templates (navbar is currently a liquid template), but converting our simple nav to non-templated html would be easy.

Even if we don't make these directories passthrough, I don't know a way we could easily use a layout to add a navbar. Layouts are wrapped around whatever content is fed in them, and we want to insert the nav inside of the content, not around it.

I am cool to hold off on starting this if it seems like we should be focusing on other things, but at the very least, I am just putting it here for reference.