Table of Contents

• Setting things up
• Workflow
  • Getting used to with Asciidoctor
  • Deployment

My website featuring a fairly customized version of my More Contentful Hugo theme.

Setting things up

You need Nix package manager installed to easily replicate the development shell for this project. Otherwise, you might have to manually install the following components:

• Hugo as it is the tool used to generate this website.

• Go runtime as the Hugo project uses Hugo modules.

• Git not only because it is the VCS this project uses but also because it is used for Hugo modules.

• Asciidoctor as it is the content markup used for the Hugo site.

• Ruby as this site uses custom Asciidoctor extensions.

• openring for generating a webring which is used on the site homepage.

With the things installed, you can just clone the Git repo of this project, run make serve, and voila! You’re now a content creator!

Most of the usual tasks done with this project should be handled by this project already which is listed in its Makefile. You can view the file for more details but for the sake of completion, here are the following tasks.

• Building the website with make serve.

• Updating the Hugo modules with make update.

• Easily creating a live server with make serve.

Workflow

The workflow should be pretty easy to get started. Here are the non-exhaustive guidelines for this project.

• You can edit any text with the text editor of your choice.

• The content uses Asciidoc markup with Asciidoctor toolchain.

• The content also uses custom Asciidoctor extensions, all of which is cited on the Gemfile.

• There is a Ruby gem for our own Asciidoctor extensions which is living at ./gems/.

The posts from this website have a certain folder structure to follow. All of them should have a dedicated folder named $PUBLISH_DATE_IN_ISO_FORMAT-$POST_TITLE_IN_KEBAB_CASE. For example, if you have a post titled "How to pick your nose" published on March 31 of 2023, you have to store it in a folder 2023-03-31-how-to-pick-your-nose in the content Hugo folder. You can easily create one with hugo new posts/$FOLDER_NAME/index.adoc.

Getting used to with Asciidoctor

This Hugo project uses Asciidoc markup with Asciidoctor due to more markup features found in it compared to Markdown. Not to mention, it easily allows extending the markup with its API which this project also makes use of. To get it working, you need to install the Ruby gem found in ./gems/.

Note	If you have Nix, this is already handled for you so feel free to skip the following section.

• Build the gem in the gems directory (i.e., cd gems && gem build asciidoctor-foodogsquared-extensions.gemspec)

• Install the gem (i.e., gem install ./asciidoctor-foodogsquared-extensions-1.0.0.gem).

• With the gem installed, you can make use of the Asciidoctor extensions from it.

Here’s a couple of macros with this extension.

• An inline macro for easily linking manpages in a variety of websites (i.e., man:crontab[5], man:systemd.unit[5]).

• An inline macro for GitHub (i.e., github:foo-dogsquared/nixos-config[], github:NixOS/nixpkgs[]) and GitLab (i.e., gitlab:gitlab-org/gitlab).

• Yet another inline macro for linking SWHIDs (i.e., swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[], swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505[]).

For more details, you can see ./gems/lib/asciidoctor for more details.

Deployment

This project uses Netlify to deploy the website. However, this uses GitHub Actions to build the website since Netlify is too limited for our this project needs.

The building step for this website should be the same as the (encouraged) workflow with Nix development shells. Hence, it should be run with make build and deploy the website with public/ folder.