Building a static website in 2024?
As the first technical post of this blog, it seemed natural to describe the design of the blog itself. A change of pace from data science.
What Follows Will Probably Be Wrong
The blog will evolve over time: it would be surprising if we had anticipated all the useful features at once. What is described here will therefore probably not match the current version of the blog that you are reading now in 2067.
Simplicity
The goal is to have a site on which to publish exclusively text, occasionally accompanied by some images. Therefore, nothing interactive. No comments. No videos either. Even less of a plugin towards a completely tapped conversational agent like ChatGPT. In short, we aim to build a site with a minimalist presentation that does not distract the reader from the content - hoping that there is, indeed, content. A static site, that is. A site whose content does not vary depending on the reader.
Local product
There are many static site generators available in 2024: Astro, Jekyll, Hugo. But well, installing 600 MB of obscure dependencies for a task (presumably) so simple, is off-putting. Considering that we will probably encounter version issues. Juggling Python versions is quite enough for us.
Moreover, slogging through documentation, spending hours on Stack Overflow, or reading source code to find the right configuration that works is not super exciting. Generally, we don't come away with anything intelligent from it; too specific, nothing useful. It works, but why? Especially since web technologies have this annoying tendency to become obsolete as soon as you look away for 5 minutes.
Thus, we developed our own solution. Like Ploum, for example. Of course, we suspect a NIH syndrome. And we watch out for the unknown unknowns lurking in the shadows ready to bite us in the face. On the other hand, if one can no longer simply write an HTML page in 2024, then the web has greatly regressed.
Python
A static site generator is not just a simple HTML page. It's a compiler to HTML, among other things. In other words, a program that takes text (in a certain language) as input and transforms it into HTML that the browser can then display. If all goes well.
To write this program, we chose Python, a vulgar language that does everything, but poorly. Thus, we sacrifice elegance for efficiency. Because the goal is to have a site, not to define an ideal web architecture based on algebraic effects. If we had the time, we would have written it in Haskell or in Brainf*ck..
The virtual environment manager pipenv comes into play immediately, and pyenv will join if the local versions of Python do not match. Markdown
A desired feature is the ability to write text in Markdown, a very convenient format and less hairy than LaTeX, and to automatically convert it to HTML. Again, it's a compilation. This functionality is reasonable and offered by many available generators.
It would be foolish to write the Markdown to HTML compiler ourselves: the honest Python package markdown does it very well.
I Speak Wall Street English
Texts are written in french. As people mostly to not read it, some (all?) will be translated to half-broken english. We have a life outside of computer science and the progress of automatic translation has been fabulous in recent years; we therefore use tools like Deepl or the other one without any shame. Since the site is static, this implies doubling all the Markdown posts and all the HTML pages. For general pages (like the index) and different components (like the navigation bar), we used a translation dictionary for each language. There is still one version per language for general pages, but the goal is to move to a single one.
Jinja
A web page typically consists of a header, a footer, a navigation menu, and other elements that remain unchanged on every page. To avoid manually copying all these elements (without making mistakes), we use the well known template engine Jinja. Moreover, we stuff the templates with lots of variables, for example to obtain the translation of words in the displayed language.
Again, it's about compilation: a layer of HTML that will be stripped down.
CSS
We aim to avoid JavaScript as much as possible, but not CSS. This implies using the Sass compiler because it slightly mitigates the horror that is CSS. Here too, for the sake of lightness, we avoid (for now?) frameworks like Tailwind CSS.
Typography
Typography is an important and often neglected subject. We followed the recommendations of Matthew Butterick, and, let's mildly acknowledge, we shamelessly copied the style of his blog. The fonts used are IBM Plex, Charter and Terminal Grotesque.
GitLab
We organize all these tools so that everyone can find their way, especially by separating each language (Python on one side, Markdown on the other, Jinja templates elsewhere, CSS in another place, etc.). And we put everything on GitLab. Here. That way, you are free to take the code and do with it what you will.