How This Site Is Built

I haven’t done a post on the process that goes into turning an idea into a post on this site, so here it is!

It start with a git repo to hold all the bits I need to actually turn a jumble of Markdown files into proper and decent-looking website.

The blog source is at Sourcehut on my blog repo.

Taking a look at the tree tab you’ll see all the files. Most of them are related to the project I use to do all the building of the site, bic, so check that out for more info and I’ll cover the important bits here that aren’t in that documentation.

For styling, I use simplecss as a lightweight, low-complexity framework that loads quickly and looks pretty good.

From there, the important bits are the following:

• pages/
• posts/
• .build.yml

pages/ include any top-level things I want to include in _header.html that shouldn’t be included in the general list of posts.

I’ll skip .build.yml for now and come back to that later.

posts/ is where all the content goes. Each post starts as a Markdown file there prefixed with a number used for post sorting on the site. For actual writing I go between neovim using astronvim and Apostrophe for a distraction-free GUI editor.

Once I’m finished writing a post, I’ll add it to the preview branch that ends up deploying to https://preview.fossen.dev/ for some final validation of what it will look like “for real.”

Coming back to that .build.yml we skipped over earlier, on a git push it kicks off a job on the sourcehut build service. You can see all the jobs specific to my blog build here.

Digging into what it’s doing some more:

image: nixos/unstable
oauth: pages.sr.ht/PAGES:RW
packages:
  - nixos.nixUnstable
  - nixos.git
  - nixos.python3

First it uses the nixos/unstable image provided by Sourcehut. If you haven’t heard of Nix and NixOS before, please check it out! It deserves its own post some day and I can’t do it justice in one paragraph so I’ll just leave the link for now.

The oauth line gives it access to publish to the sourcehut pages service that actually hosts the content.

Next it installs all the Nix packages provided. We need (but probably don’t with recent versions) the unstable version of nix, git to pull a different repo, and python3 for a tool to fix file times.

Moving on to the tasks:

tasks:
- fix-mtime: |
    git clone https://github.com/MestreLion/git-tools.git
    pushd blog
    python3 ../git-tools/git-restore-mtime
    popd
- check-branch: |
    pushd blog
    if git branch --contains=$(git branch | head -n1 | awk '{print $NF}' | tr -d ')') | grep -q master ; then
      echo SITE="fossen.dev" >> ../vars
      echo SITE_URL="https://fossen.dev" >> .env
    else
      echo SITE="preview.fossen.dev" >> ../vars
      echo SITE_URL="https://preview.fossen.dev" >> .env
    fi
    popd
- package: |
    cd blog
    nix --experimental-features nix-command --extra-experimental-features flakes run  github:Pinjasaur/bic .
    cd build
    tar -cvz ./ > ../../site.tar.gz
- upload: |
    source ./vars
    acurl -f https://pages.sr.ht/publish/$SITE -Fcontent=@site.tar.gz

First work around an issue with git by using git-restore-mtime.

Then check which branch we’re one to decide if this is a real deploy or going to the preview site.

Then to the actual building, here’s where in the past the unstable version of the nix tool was needed but should be available by default now. Since bic provides a flake.nix, we can pull and build from that directly which gives us a nice self-contained build that doesn’t depend on system-to-system differences getting in the way of building. As long as we’re running Nix, we should be able to build it the same way each and every time!

At the end of the package task, we tar up the final, built site for later uploading.

Finally, we use a provided tool by the build server, acurl that gives us an authenticated curl to use to upload the compressed site to Sourcehut Pages, which takes care of unpacking that and serving the contents on the site.

As a final final step, if everything looks good I pull the post from preview into the master branch and push which runs the build and deploy steps for the main site.

And that’s it! It’s been working pretty well for awhile now and I don’t have any real complaints. Tags in bic would be a nice-to-have (and is being tracked in this issue). Possibly some ability to schedule posts or some automatic promotion from preview to master would be nice, both of which would need to be scripted because they aren’t available as part of Sourcehut’s feature set.