Jekyll Publisher

This is a quick hacky script I wrote in Rust to allow quickly setting up a github pages Jekyll repo to publish with plugins enabled.

By default Github pages blocks plugins, so when the site is built by Github on a push to main the plugins do not run.

This was a problem for my journal site as it has a tag generating plugin I wrote that needs to run during the build phase to generate tag index pages.

To get around this, jekyll build needs to be run locally instead of by Github. The built artifacts are then what should be pushed to the main branch for Github to serve for the site.

This script sets up the repo to achieve this, and can be used each time a new version of the site needs to be published.

How to use it

First build the project:

cargo build --release

The compiled binary will be in target/release/rust-jekyll-publisher.

Copy or link this binary to the root of the github pages repository that needs to be set up.

Run the following to set up the repository for building locally:

./rust-jekyll-publisher setup

The setup command will:

• Run jekyll build to create the built artifacts in the _site subdir
• Add _site to .gitignore
• Checkout a new sources branch, commit and push there
  • The sources branch is where the build sources now live, e.g. the markdown files that are used to generate the built artifacts
• Initialise a new git repository inside the _site subdir
• Set the same remote in this newly initialised repository
• Make an initial commit and force push to the main branch
  • The main branch now only has the compiled assets (the contents of the _site subdir)
  • Github now detects that it is compiled assets and not a Jekyll site on the main branch and so does not attempt to build with Jekyll each time something is pushed to main

After setup the workflow for publishing updated versions of the Jekyll site should be as follows:

• Make changes to the source files and commit, pushing to the sources branch
• Run jekyll build to update the compiled assets in _site
• From within _site, make a new commit and push to the main branch

The last two publishing steps above can be performed with:

./rust-jekyll-publisher publish

You will need to commit changes to the source files first or the command will panic.

The benefit of the above is that the source files are still under version control (on the sources branch), and the main branch includes the compiled assets including those generated by plugins.