@rossjrw hope you don't mind me tagging you in here but I'm having trouble understanding what about the config needs to change for the preview link to come up as https://numist.github.io/highlight-css/pr-preview/pr-15/ (instead of https://numist.github.io/highlight-css/docs/pr-preview/pr-15/, which doesn't exist)

It looks like changing umbrella-dir will fix the output link but break the preview location (putting it at the root of the repo instead of in /docs)? Am I missing something obvious here?

No worries @numist.

If my understanding of what you're trying to do is correct, you're deploying to GitHub Pages from the docs/ dir on the main branch (as opposed to my documentation's assumed default of deploying from the root dir on the gh-pages branch). So you want to place preview files into the docs/ dir on the main branch, and you want the URL that the action reports back not to have docs/ in it.

I think this is a difficult way of going about things. That's not to say it's wrong, or that I know any better than you about what's best for your codebase. But I think it might cause you a couple of issues down the line.

Consider this situation:

• You start a new feature and open a pull request for it - let's say pull request 1
• A preview is generated at docs/pr-preview/pr-1/.
• You think of a great idea for a new feature and immediately start work on it. You open a pull request, let's say pull request 2
• A preview is generated at docs/pr-preview/pr-2/
• The second preview, because it's previewing all changes to the docs/ dir, contains a copy of preview 1, at something like docs/pr-preview/pr-2/pr-preview/pr-1/
• If you then do more work on PR 1, the resulting preview will include a preview of its changes to PR 2's preview - something like docs/pr-preview/pr-1/pr-preview/pr-2/pr-preview/pr-1/
• And so on

You could probably avoid this happening by careful application of ignore rules, manual steps to delete junk files, etc. But IMO it's a lot easier to avoid that happening in the first place.

One rule I personally try to stick to is that the main branch should only contain files written by humans. For my repos that use GitHub Pages, I deploy from the gh-pages branch and I make sure any generated files (e.g. PR previews) are put there, not in my main branch.

I notice that you had a gh-pages branch but got rid of it in #13. I could be wrong, but it looks like you were maintaining two sets of human-written files, one in main and one in gh-pages? If that's the case, moving those files into the main branch was absolutely the correct decision. Given the assumption that all of the files in your repo are written by real people and you don't need anything fancy, it's a valid simplification - but PR previews are what I would call 'fancy', and I beieve adding a small layer of abstraction will simplify things.

Given that your site now includes a mix of human-written and machine-generated files, I think you should be deploying your Pages site from a staging branch e.g. gh-pages, just to sandbox it away from everything else.

So here's what I'd do:

I would create two Actions workflows - one to deploy the Pages site to the gh-pages branch on push to main, and another to handle previews. I like https://github.com/JamesIves/github-pages-deploy-action, so that would look something like this:

1. First, a workflow that, on push to the main branch, simply copies the contents of docs/ on main into the root dir on gh-pages:

# .github/workflows/build.yml

name: build
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: docs/
          clean-exclude: pr-preview/

2. Second, a preview action that simply adds preview files to gh-pages:

# .github/workflows/preview.yml

name: preview PRs
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
    paths:
      - docs/**
      - .github/workflows/preview.yml
concurrency: preview-${{ github.ref }}
jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Deploy preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: docs/

Then configure your Pages site to be deployed from gh-pages. If all goes well it'll work invisibly. Plus the URL will be correct!

I notice that you had a gh-pages branch but got rid of it in #13. I could be wrong, but it looks like you were maintaining two sets of human-written files, one in main and one in gh-pages? If that's the case, moving those files into the main branch was absolutely the correct decision.

Basically yes, though what's even weirder is that the ultimate goal is for all files except Makefile and most of docs/index.md to be fully automated (tracked by #6):

• @dependabot opens a PR that bumps Gemfile.lock and/or requirements.txt
• custom pull-request action rebuilds the repo's contents (including docs) and commits changes into the branch
• preview action validates that nothing went horribly wrong
• auto-merge when all checks complete.

To your point, probably the "rebuild succeeded" check is all thats really necessary and a preview system that checks previews into the repository is not especially compatible with this scheme; I've just suffered too much drycoding Markdown + Liquid and would love to stop committing incomplete sins to main.