website/README.adoc

= blog
:toc:

My website featuring a fairly customized version of https://github.com/foo-dogsquared/hugo-theme-more-contentful/[my More Contentful Hugo theme].




== Setting things up

You need link:https://nixos.org[Nix package manager] installed to easily replicate the development shell for this project.
Otherwise, you might have to manually install the following components:

- link:https://gohugo.io/[Hugo] as it is the tool used to generate this website.
- https://go.dev/[Go runtime] as the Hugo project uses link:https://gohugo.io/hugo-modules/[Hugo modules].
- Git not only because it is the VCS this project uses but also because it is used for Hugo modules.
- link:https://asciidoctor.org/[Asciidoctor] as it is the content markup used for the Hugo site.
- link:https://www.ruby-lang.org/en/[Ruby] as this site uses custom Asciidoctor extensions.
- link:https://git.sr.ht/~sircmpwn/openring[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 link:Makefile[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 link:Gemfile[`Gemfile`].
- There is a Ruby gem for our own Asciidoctor extensions which is living at link:./gems/[`./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 link:https://git-scm.com/docs/git-worktree[Git worktree].
Mostly, it is expected to be in a directory inside of the project.

[source, shell]
----
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 link:./gems/[`./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 link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHIDs] (i.e., `swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`, `swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505[]`).

For more details, you can see link:./gems/lib/asciidoctor[`./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 link:http://gohugo.io/content-management/taxonomies/[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.


== Copyright

The template used for this site is licensed under MIT license which you can link:./LICENSE[view the file in full detail].
The link:./content/[content that is hosted in here] are my intellectual property.