Enable github forks to override jekyll config

The github build action will dump a `JEKYLL_CONFIG_OVERRIDES` action
variable into a file `_config-overrides.yml` which will override
whatever you want in `_config.yml`.

Why:

It's convenient to be able to deploy the website on a forked repository.
Currently this doesn't work smoothly because by default with actions
because it builds with kroxylicious.io as the url. The mechanism that
configures the baseurl is also not wired up correctly.

To override the url we need to add in an override configuration, so I
figure we should use the same mechanism to override baseurl. The fork
can set a variable containing both these values.

Signed-off-by: Robert Young <[email protected]>

Author: robobario

.github/workflows/jekyll-gh-pages.yml

@@ -59,6 +59,9 @@ jobs:
           tags: localhost:5000/kroxy-jekyll:latest
           cache-from: type=gha
           cache-to: type=gha,mode=max
+      - name: Load Jekyll configuration overrides
+        # this is to enable forks to override the url and baseurl
+        run: echo "${{ vars.JEKYLL_CONFIG_OVERRIDES }}" > _config-overrides.yml
       - name: Build with Jekyll
         # Outputs to the './_site' directory by default
         run: |
@@ -67,7 +70,7 @@ jobs:
             -u "$(id -u):$(id -g)" \
             -v "$(pwd):/site" \
             localhost:5000/kroxy-jekyll:latest \
-            bash -c 'eval "$(rbenv init -)" && cp -r /css/_sass/bootstrap /site/_sass/ && bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"'
+            bash -c 'eval "$(rbenv init -)" && cp -r /css/_sass/bootstrap /site/_sass/ && bundle exec jekyll build --config=_config.yml,_config-overrides.yml'
         env:
           JEKYLL_ENV: production
       - name: Upload artifact

.gitignore

@@ -5,4 +5,5 @@ _site
 vendor
 .idea
 *.iml
-*/bootstrap/
+*/bootstrap/
+_config-overrides.yml

README.md

@@ -27,6 +27,26 @@ To build and serve the website from a container you can run `./run.sh`. It will
 
 This assumes the use of `podman`, if you are a `docker` user you can run `CONTAINER_ENGINE=docker ./run.sh`.
 
+### Running on GitHub Pages on a Fork
+
+To exercise the GitHub workflows and share changes it can be convenient to deploy a fork to GitHub Pages.
+
+To enable pages on your fork:
+1. go to `https://github.com/${yourname}/kroxylicious.github.io/settings` in a browser, replacing `${yourname}` with your GitHub username.
+2. Navigate to "Pages" under "Code and automation"
+3. Under "Build and deployment", under "Source", select "Github Actions".
+4. Navigate to "Actions" under "Secrets and variables" under "Security"
+5. Select the "Variables" tab
+6. Click "New repository variable"
+7. Create a new repository variable named `JEKYLL_CONFIG_OVERRIDES` with value:
+   ```yaml
+   baseurl: "kroxylicious.github.io"
+   url: "https://${yourname}.github.io"
+   ```
+   replacing `${yourname}` with your GitHub username.
+8. Push changes to any branch of your fork and then trigger a manual run of `https://github.com/${yourname}/kroxylicious.github.io/actions/workflows/jekyll-gh-pages.yml`,
+   supplying the branch you want to checkout and deploy as a parameter. 
+
 # Binary content
 
 We have an ever-growing collection of binary assets, mostly images but also a few PDF slide decks etc all of these