Table of Contents

• Setting things up
• Workflow
  • Getting used to with Asciidoctor
  • Asciidoctor custom include processors
  • General content taxonomy
  • Deployment
• Project development guidelines
• Copyright

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.

• Ruby as this site uses Asciidoctor and custom Asciidoctor extensions.

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

• ImageMagick for processing the image files.

With the things installed, you can just clone the Git repo of this project, run rake 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 Rakefile. You can view the file for more details but for the sake of completion, here are the following tasks.

• Building the website with rake serve.

• Updating the Hugo modules with rake update.

• Easily creating a live server with rake 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.

Take note you also have to fetch the branches with the content/ prefix. Each of those branch are basically dedicated branches for content which can be retrieved inside of the Asciidoctor document. Another thing to set up is to create a Git worktree. Mostly, it is expected to be in a directory inside of the project.

git worktree add ./code-workspace

The above directory is typically used for the content/* branches.

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.

Asciidoctor custom include processors

This website uses its own set of Asciidoctor extension as depicted from the above section. But there are more than shorthand macros for certain types of link.

The most useful (arguably) types of extension found here are the include processors.

• An include processor for retrieving Git objects with git:. This might not sound great but it allows me to create dedicated branches for certain content. Plus, it easily creates patches which is nice to create code walkthroughs.

• An include processor for SWHIDs but only with content blobs (i.e., swh:cnt:). Very useful for referring to archived codebases.

General content taxonomy

While this is mostly referring to Hugo taxonomies, this is generally applicable to similar features found in other site generators. The way how I describe the relationship of the content for the end user is pretty simple as it only contains two taxonomy: tags and series.

• Each content may have multiple tags attached to them. These tags are basically referring to a field of various scopes. It can go from a very broad field (e.g., Programming) to a specific one (e.g., Web development). I recommend to be as specific as possible with the tags.

• Each content can be a part of a series. A content can only be one series at any given time. A series is typically encompassing in its scope and should have an introductory post as to what it is and its aims.

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.

Project development guidelines

This project is developed with some habits. The following non-definitive list show those habits.

• This project uses a custom Ruby bundler for Nix environments. It only needs gemset.nix but it is generated from Gemfile.lock. To generate them, you can run the following command:

  nix run github:sagittaros/bundix -- -l

  Take note you need to do this every time you change the Ruby environment.

• It needs content/* branches to be deployed with the site. This is because several posts uses a an Asciidoctor extension to include content from other Git revisions. This means you have to fetch them into your local Git repo.

  git fetch origin +refs/heads/content/*:refs/heads/content/*

  You can easily a dedicated content branch with ./bin/switch-content-orphan-branch.rb.

• For content drafts, it is recommended to create a dedicated branch for it. This branch needs to have a prefix of drafts/ with the filename relative to the content directory (e.g., drafts/posts/2023-03-26-how-to-pick-your-nose). This step is already automated with ./bin/create-draft-branch.rb.

• Consequently with previous guideline, it is recommend to commit daily and commit often with the drafts. Once it is done, a rebase should be done with a squashed commit publishing the content.

• The avatar images are processed with ImageMagick. Furthermore, they should be optimized. The simple avatar designs such as ./assets/svg/avatars/ezran/default.svg can be reduced and optimized up to 90% of its quality. Though, this depends on the encoding of the format (e.g., WebP, AVIF). The following command should show how it is done.

  magick convert $AVATAR -quality 30 $AVATAR_OUTPUT

Copyright

The template used for this site is licensed under MIT license which you can view the file in full detail. The content that is hosted in here are my intellectual property. However, code samples from the content are dual-licensed under MIT and AGPLv3.