Building its own static building system is a rite of passage for many developers.
It has a lot of nice features.
It gives a goal with a feeling of accomplishment.
It is simple enough so most developers could build their own system.
But it could also become very complex when you go down the rabbit hole.
Along the years I used different tools and used and wrote of few static
website systems:
- [[https://nanoc.app][nanoc]] (in Ruby), at that time it looked like this: [[https://web.archive.org/web/20081002071448/http://nanoc.stoneship.org/][old nanoc 2 website]]
So if you look at the progression, I first used nanoc because I used ruby
and it was a very new solution, the website looked really great.
Also the main developer [[https://denisdefreyne.com][Denis Defreyne]] was really helpful.
Ruby was really great at dealing with regular expressions for hacking my
documents.
Then I was interested in Haskell, and I switched to a Haskell-made
solution.
I used hakyll, and I wrote a bit about it in [[http://yannesposito.com/Scratch/en/blog/Hakyll-setup/][Hakyll Setup]].
As a side note, the author of Hakyll [[https://jaspervdj.be/hakyll/][Jasper Van der Jeugt]] is apparently a
friend of the author of nanoc.
They both wrote a static site generators with their preferred programming
language.
I added a lot of personal features to my own site builder.
It was a nice toy project.
Then, due to a major disruption in my professional and private life I
stopped to take care of my website.
And a few years ago, I wanted to start a new website from scratch.
In the meantime I switched my editor of choice from vim to Emacs.
I started to work in Clojure and emacs is generally a natural choice
because you can configure it with LISP.
I discovered [[https://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html][org-mode]] (I don't think the homepage of org mode makes justice
to how incredible it is).
So org-mode comes with an export system.
Thus I switched to org-publish.
Again [[https://her.esy.fun/posts/0001-new-blog/index.html][I wrote a bit about it]].
It was nice, but very slow.
I improved a few things like writing a short script to
[[https://her.esy.fun/posts/0005-rss-gen/index.html][Generate RSS from a tree of html files.]]
But I still had the feeling it was too slow.
Static site building is a specific usage of a build system.
And as I knew I could use =pandoc= to build HTML out of org-mode files
and still versed in the Haskell culture I decided to try [[https://shakebuild.com][shake]].
You can learn more by reading this excellent paper about it, I
think all developer should read it: [[https://github.com/snowleopard/build-systems/releases/download/icfp-submission/build-systems.pdf][Build System à la carte]].
As a bonus, [[https://pandoc.org][pandoc]] is written in Haskell.
I could then directly use the [[https://pandoc.org][pandoc]] library in my build program.
It worked like a charm and it was *very fast* as compared to other
solutions I tried.
So really let me tell you shake is a great build system.
But it was not perfect.
While it was very fast, and I was able to use pandoc API directly.
It made me dependent on Haskell.
The best way I found to have Haskell reproducible build environment is to
use [[https://nixos.org/nix][nix]].
This was great until the Big Sur update.
To keep it short, nix stopped working on my computers after I upgraded my
to Big Sur.
Gosh, it was painful to fix.
Concurrently I discovered [[/posts/0016-gemini/index.html][gemini]] and wanted to duplicate my website into
gemini sphere.
So I tried to update my build system but my code was to oriented to use
pandoc and it was painful to have gemini in the middle of it.
Particularly, generating a gemini index file.
My main goal was to have gemini file that could only be linked from withing
gemini sphere.
Because gemini is a lot smaller web where you could feel a bit more
protected from what the Web has become along the years.
Whatever, in the end, I just had two problems to tackles.
1. Haskell became difficult to trust as very stable tool. Stable in the
sense that I would not have any support work to do in order to keep just
using it and not fixing/tweaking it.
2. Simplify the overall system to have a simpler build description
So a very stable tool that I am pretty sure will still work almost exactly
as today in 10 years is *=make=* (more precisely gnumake).
I expected a lot of people had already come to the same conclusion and
wrote about it.
To my great surprise, I found very few article about generating static
website with make.
I only found solutions a bit too specific for my need.
This is why I would like to give you a more generic starting point
solution.
* The =Makefile=
:PROPERTIES:
:CUSTOM_ID: the--makefile-
:END:
Instead of copy/pasting my current =Makefile= entirely let me give you a
more generic one.
It should be a great start.
The first part will be used to simply copy the files from =src/= to
=_site/=.
#+begin_src makefile
all: website
# directory containing my org files as well as my assets files
SRC_DIR ?= src
# directory where I will but the files for my website (HTML + assets)
DST_DIR ?= _site
# list all files in src
# if you want to exclude .org files use the exclude from the find command
SRC_RAW_FILES := $(shell find $(SRC_DIR) -type f)
# generate all file that should be copied in the site
# For my site, I want to publish my source files along the HTML files