Zola + Codeberg Pages: Deploying a Blog

Codeberg Pages

Similar to GitHub pages (which this site was originally deployed on), Codeberg has 'Codeberg pages' which uses a simliar but open technology to deploy the content of a git repository as a webpage. Similar to GitHub pages which allows you to have one uncomplicated URL tied to your repository (e.g., {username}.github.io), Codeberg does the same (morganjwilliams.codeberg.page). It has a few prerequisites:

• You'll need a public repository called pages (for the variant tied to your username; you can also set up Codeberg pages for other repositories).
• Within this, you'll need a branch called pages.
• Beyond that you'll need to setup a webhook in settings.

Moving to Zola

This site was originally built in Jekyll (a static site generator using Ruby), and I'm now using Zola (a static site generator built in Rust). Both build HTML sites from templated markdown, Zola's a bit quicker, and for the time being I find it less complex to work with.

Installing Zola

If you have Rust and cargo installed, you can build Zola from source (cargo install --locked --git https://github.com/getzola/zola), but there's a long list of binary/executable install methods on Zola's installation page. There are also prebuilt binaries in GitHub, should you wish to just use one (maybe do/don't add it to your git repo?).

Get a Theme

Like Jekyll, Zola has a decent number of themes you can use to get a leg up on styling your page (or, leave it to someone with the interest, and find something which fits your vibe). These inform both the structure and styling of the page, and while a bit of a learning curve, the main bits will likely be documented.

Looking to simplify a little from where I'd been (and the components I'd modified/made with little real understanding of what I was doing) with Jekyll, I went with serene.

Note: Themes in Zola are typically best managed as updatable git submodules; this isn't something everyone deals with every day, but it's something to consider in your build and deploy workflows.

Building Your Site

Zola has some simple commands for building your site. By default, zola build will build your site and put the contents in ./public/. zola serve will give you a live preview of content as you edit it on a local webserver. In terms of deployment, you'll typically want to run zola build and deploy the rendered content within ./public.

Without CI Workflows

Unlike GitHub, 'actions' in Codeberg are a little less plug and play, and building locally and just pushing rendered content is a viable (but repetitive) option. This is how I started, using a two-parallel-branch strategy in git - a main branch where 'structure' lives (what I build from) and a 'pages' branch where I push updates to content (HTML, mostly) which then gets rendered on Codeberg pages. I wrote a simple batch script to automate the 'build, switch branches, move things and stage changes on the pages branch' workflow.

Local Tools (of Choice/Habit)

• I'm still on Windows for my main personal PC now, so it's good old cmd and/or Powershell for a terminal.
• I use VS Code for work, and it's free, so in terms of editors, that's where it's at. I just find all the buttons to turn off anything referencing AI.
• I use GitKraken as a git GUI to save my brain a little with some git management. But, having habitually run into authentication issues as 90% of the repositories I work on are private/not feeling the need to bake in credentials into this tool, I typically push to/pull from remotes from the command line. Also turned off all the AI features here.

Using CI Workflows

Codeberg does have hosted solutions for basic workflows accessible after enabling them in a few settings (alongside their 'Woodpecker CI' solution which requires approval). I've since set up self-hosted runners for this purpose, see the post covering that here.

The action I've set up for deploying the page currently uses a self-hosted runner, builds Zola from source, builds the site, and pushes the changes to the pages branch in a simiiar fashion to how I'd done it locally prior to this. Note that the caching of Zola/cargo is a work in progress (it'll need some modifications to work...), but this should minimise the computational load until a new version of Zola is requested in the workflow.

serene Reactions

I'm not tracking you when you visit here, and as it's a static site you'll not have a great deal of interactivity here, and I won't know you've been (feel free to ping me on Mastodon @metasomite though!), making it feel very 'shout into the ether'. To slightly remedy this and give an option for anonymously noting 'I was here', I've followed serene's guide to adding a basic reactions endpoint using a basic Cloudflare database and a hundred or so lines of Typescript defining the endpoint to allow each post to have reactions at the bottom. If I'm missing one you'd rather use, let me know...

As I have cargo installed locally (will get to talking about Rust one day), I used fnm to install Node; note the shell setup step if you want to follow along, in my case using Powershell.

Using a Custom Domain

If you don't want to have {username}.codeberg.page as your domain, you can fork out for a custom domain from one of the many registrars. To use a custom domain to host your site on Codeberg Pages, at the root of your pages branch of your repository, you'll need a file called .domains containing your domain at the top.

Note that the workflow contained in the Zola instructions for getting set up on Codeberg Pages contains a step which would remove the .domains (git rm -r "*" || true) and return an associated error in your page when deployed; in my deployment workflow I've modified this to refer to specific filetypes/avoid the . files with git rm -r *.html *.json *.xml *.txt *.js *.css *.jpg *.png || true - YMMV.

You will also need to set up some custom DNS (I needed this variant).