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`.
There is another thing that this project uses which is set of dedicated branches for containing code for certain posts.
For example, the content branch `content/posts/2023-03-31-how-to-pick-your-nose` contains code walkthroughs to be used on the same content from the content directory.
This setup allows us to easily write code walkthroughs.
Speaking of extending Asciidoctor, we use our own set of custom Asciidoctor extensions https://github.com/foo-dogsquared/asciidoctor-foodogsquared-extensions[deployed with RubyGems].
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.
The following non-definitive list show those habits.
- This project uses link:https://github.com/sagittaros/ruby-nix[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:
+
--
[source, shell]
----
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 link:./gems/lib/asciidoctor/git-blob-include-processor[an Asciidoctor extension to include content from other Git revisions].
This means you have to fetch them into your local Git repo.
You can easily a dedicated content branch with link:./bin/switch-content-orphan-branch.rb[./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 link:./bin/create-draft-branch.rb[`./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 link:./assets/svg/avatars[avatar images] are processed with ImageMagick.
Furthermore, they should be optimized.
The simple avatar designs such as link:./assets/svg/avatars/ezran/default.svg[./assets/svg/avatars/ezran/default.svg] can be reduced and optimized up to 90% of its quality.
