Blogging with weblog.lol and GitHub actions
My blog is run on omg.lol's weblog.lol service. Weblogl.lol is fantastic product due to it's extreme simplicity.
Until very recently, weblog.lol didn't have support for images, or static assets (such as CSS or JS files), though, so if you wanted those you needed to manage them yourself.
In this blog post I'm outlining how I'm using a GitHub action and the weblog.lol API to manage my blog in Git, rather than through their web interface.
weblog.lol provides a bit of a reference implementation for this. I downloaded the php script referenced in there, and based my implementation around this. However I wanted more features: Specifically, I wanted to manage CSS, JS, and image files all in the same repository.
Pre-requisits
What I want to achieve is the following:
- When authoring posts or templates, I want to reference images, stylesheets and JS files using relative URLs that point to the correct place in the repository. That way any of my local previews will work just fine.
- My static files (CSS, JS, images) should be uploaded automatically when publishing.
- The relative references I used for authoring, should be replaced with absolute references to the relevant file when publishing.
- Additionally, I want to append a query string with the MD5 hash of the file to all these URLs, for cache busting. (I use CloudFlare to cache responses from my B2 bucket with a very long lifetime, so this is an absolute necessity for me.)
Block storage
Because weblog.lol has nowhere to upload static assets, such as images, CSS and JS files, you'll need to find somewhere to upload these to. I've been using Backblaze B2 for my Mastodon instance and so that was a natural choice. Any other AWS S3 compatible storage would work in the same way, and there are a lot of other options as well.
Git Repository directory structure
This is somewhat arbitrary, but based upon the reference implementation, I decided on the following:
-
configuration/configuration.txt
contains the main configuration file. -
configuration/template.html
contains the main template. -
css/*
contains my CSS files. -
images/*
contains my images. -
js/*
contains my JS files. -
script/*
contains some scripts needed for deployment -
weblog/*
contains markdown files for any posts, pages, and templates. -
drafts/*
contains markdown files for any drafts.
My Workflow
In order to accomplish all of these aims, I've created the following file at .github/workflows/main.yml
:
on: [push]
jobs:
weblog_import:
runs-on: ubuntu-latest
name: weblog.lol
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Rewrite references to static assets
run: php -f script/pre-process.php ${{github.event.before}} ${{github.sha}}
shell: bash
- name: Upload Images
uses: shallwefootball/upload-s3-action@v1.3.0
with:
source_dir: 'images'
aws_key_id: ${{ secrets.AWS_KEY_ID }}
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
aws_bucket: ${{ secrets.AWS_BUCKET }}
endpoint: ${{ secrets.AWS_ENDPOINT }}
destination_dir: 'images'
- name: Upload JS
uses: shallwefootball/upload-s3-action@v1.3.0
with:
source_dir: 'js'
aws_key_id: ${{ secrets.AWS_KEY_ID }}
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
aws_bucket: ${{ secrets.AWS_BUCKET }}
endpoint: ${{ secrets.AWS_ENDPOINT }}
destination_dir: 'js'
- name: Upload CSS
uses: shallwefootball/upload-s3-action@v1.3.0
with:
source_dir: 'css'
aws_key_id: ${{ secrets.AWS_KEY_ID }}
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
aws_bucket: ${{ secrets.AWS_BUCKET }}
endpoint: ${{ secrets.AWS_ENDPOINT }}
destination_dir: 'css'
- name: Import weblog
run: php -f script/import.php nanos ${{ secrets.WEBLOG_API_KEY }} ${{github.event.before}} ${{github.sha}}
shell: bash
So, let's run through what this script does:
Every time I push any changes to GitHub, the following actions will be performed:
- We firstly check out the latest version of the repository.
- Then we run a script, located at
script/pre-process.php
. You'll find a full copy of that script below, but here is a summary of what this script does:- It firstly calculates md5 hashes of all images, CSS, and JS files.
- It then gets a list of files that have changed in this push.
- For each changed markdown or html file, it replaces relative references to the static files with absolute references, including the md5 hash, calculated earlier.
E.g. if I have authored a post with

, this will now be referenced as
It also does the same for all my templates (regardless of whether these have changed or not), simply because I frequently change my CSS/JS files without touching the templates. So these get synced with every push, regardless of necessity. - Finally, it deletes any unchanged CSS, JS, and image files. Why? well, because we are going to upload all files in the
images
,css
, andjs
directories to B2, and we don't want to upload unchanged files over and over and over again.
- We upload any images, JS, and CSS files to B2
- Finally run a script
script/import.php
, which will import any changes into weblog.lol. I'm mostly using the provided reference implementation here, though I've removed some bits and pieces. Again, you'll find a full copy of this script below, but here is a summary of what it does:- It again gets a list of files that have changed in this push.
- It then adds files that were changed by the
pre-process.php
script (mostly the templates). - Finally, it simply submits all changed files to weblog.lol's API
Summary
So that's how I write this blog. I enjoy authoring in my local text editor much more than in the weblog.lol interface, among others because I use VS Code, with the Markdown preview built-in, so I get live previews while authoring.
The Scripts
This is my pre-process.php
script:
This is my import.php
script: