1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
|
---
title: "Adventures in making this website:<br>static site generation"
date: 2022-11-15
layout: "blog"
toc: true
---
Published on 2022-11-15, last updated on 2023-02-27.
Making and managing this personal website has been an adventure.
In this series, I go over the technical challenges I've encountered
and philosophical decisions I've made,
and I review some of the tools I've used along the way.
This is part 1, followed by [part 2](/blog/2022/website-adventures-basics/),
[part 3](/blog/2022/website-adventures-maths/)
and [part 4](/blog/2023/website-adventures-images/).
If you've ever taken a good look at HTML,
it should be clear that it isn't fun to write it all by hand.
Therefore, we invented the Static Site Generator (SSG):
a program that takes an HTML template and some text
in a more human-friendly form (usually Markdown),
and mashes them together, yielding a servable HTML file.
Of course, it's pretty clear what the best approach to do this is,
so we only need one SSG, right?
<a href="https://xkcd.com/927">
<img src="https://imgs.xkcd.com/comics/standards.png" style="border: 5px solid #ffffff;">
</a>
Yeah... no, there are [a lot of them](https://jamstack.org/generators/).
Frustratingly many, in fact.
Although some of them are highly specialized or advanced,
most are very similar in scope.
The three SSGs I'm about to discuss
are all intended for personal blogs,
and for many people, there isn't much reason to prefer one over the other.
My SSG-hopping was due to my niche requirements and perfectionism.
## Zola
The first SSG I used was [Zola](https://www.getzola.org/),
which was started in late 2016 (making it the youngest SSG here),
and advertizes itself as a *"one-stop static site engine"*
that *"gets out of your way so you can focus on your content"*.
Written in Rust, it's fast and portable,
and has convenient features like code syntax highlighting,
support for multilingual sites, and an optional theme library.
Similar to other SSGs, you can run `zola serve` to start a local HTTP server
to test a webpage, which reloads itself each time you make changes;
this makes development a breeze.
### Demonstration
An example can say more than a thousand words,
so, to give an idea of what it's like to use Zola (other SSGs are similar),
consider this HTML template,
powered by [Tera](https://tera.netlify.app/):
```html
{% raw %}<html>
<head>
<title>Example</title>
</head>
<body>
{% block content %}
{{ section.content | safe }}
{% endblock content %}
</body>
</html>{% endraw %}
```
This is a standard HTML document, except for the parts in curly braces:
`{% raw %}{% %}{% endraw %}` is for statements,
and `{% raw %}{{ }}{% endraw %}` inserts the value of an expression into the output.
We've created a block `content`, and given it the default definition
`{% raw %}{{ section.content | safe }}{% endraw %}`,
where `section.content` is the content of this "section"
after Markdown-to-HTML conversion
(Zola distinguishes *sections* and *pages* based on folder structure and file name).
Then `safe` tells Tera that the string has been fully converted to HTML,
so no more escaping is necessary.
The point of defining such blocks in the template
is that you can override them.
We thus create a page template which inherits the above structure
(`{% raw %}{% extends "default.html" %}{% endraw %}`)
and redefines the `content` block.
This example also highlights Zola's neat table-of-contents generation:
```html
{% raw %}{% extends "default.html" %}
{% block content %}
<div id="title">{{ page.title }}</div>
<p>
<ul>{% for h1 in page.toc %}
<li><a href="{{ h1.permalink | safe }}">{{ h1.title }}</a>
{% if h1.children %}
<ul>{% for h2 in h1.children %}
<li><a href="{{ h2.permalink | safe }}">{{ h2.title }}</a></li>
{% endfor %}</ul>
{% endif %}</li>
{% endfor %}</ul>
</p>
{{ page.content | safe }}
{% endblock content %}{% endraw %}
```
Okay, enough templates, what if we actually want to write something?
Well, then we just create a Markdown file in the appropriate place
(I'm being vague, since this isn't intended to be a tutorial)
with contents like:
```markdown
+++
title = "Example page"
+++
# Heading 1
Lorem ipsum dolor sit amet...
```
The part surrounded by `+++` is called the *front matter*,
and is a common feature in SSGs, allowing you to set parameters
that can be used by templates or the SSG itself.
And that's it! If we now run `zola build`,
our Markdown will be converted to HTML and inserted into the template.
### Review
Zola's opinionated design pays off:
it's quite simple, fast and as flexible as your templates allow.
Speaking of which, of the SSGs I've tried,
Tera is in my opinion the cleanest and most powerful template engine.
Zola's main weakness is its obscurity:
if you need help or want to do complex things,
there aren't many resources available other than the official documentation.
But I also think its design is good enough
that you can probably figure it out.
So, why did I stop using Zola? Due to a giant misunderstanding, that's why.
In late 2020 I started my [knowledge base](/know/),
for which I needed the ability to show maths formulas.
There exist several solutions to put LaTeX maths on websites,
but back then I didn't understand how they worked and what their prerequisites were,
so I mistakenly concluded that it wasn't possible with Zola.
Indeed, Zola doesn't have built-in support for it,
but it turns out I didn't need that!
And I only figured that out while writing this post...
I'll go over my maths rendering journey in a future article.
In the end, my misguided decision to migrate from Zola did have some benefits;
otherwise my current offline solution wouldn't have been possible.
But in hindsight, I wish I'd spent more time with Zola,
and I think it would be my first recommendation to a beginner.
## Hugo
I migrated to [Hugo](https://gohugo.io/), an SSG written in Go,
which also markets itself as being fast and flexible,
and is pretty much feature-equivalent to Zola.
Hugo is much more popular than Zola;
in fact, it seems to be one of the most-used SSGs out there.
The reason I chose it is that it allows page contents to be written in one
of [several formats](https://gohugo.io/content-management/formats/#list-of-content-formats),
one of which is [pandoc's](https://pandoc.org/) Markdown dialect
that has built-in support for LaTeX maths.
So when Hugo is building the site, it passes my `.pdc` file to the external `pandoc` program,
which converts it to HTML to insert into the template.
With how Hugo sets this up, the result is that all maths
get wrapped in HTML `<span>` tags with certain classes,
which I (wrongly) thought was necessary.
### Demonstration
The previous page template example would look like this in Hugo,
after a few small tweaks like adding a navigation bar at the top of the page:
```html
{% raw %}<html>
<head>
<title>{{ .Title }} | {{ .Site.Title }}</title>
</head>
<body>
{{ partial "navbar.html" . }}
<div id="title">{{ .Title }}</div>
{{ .TableOfContents }}
{{ .Content }}
</body>
</html>{% endraw %}
```
On the one hand, Hugo provides the convenient `.TableOfContents` variable
at the cost of control, unlike Zola, where we had to do it
manually. ~~On the other hand, Hugo doesn't use block-based templates
and hence lacks a nice inheritance system like Zola's~~
[I stand corrected](https://lobste.rs/s/x2bknz/adventures_making_my_website_static_site#c_jbmpl2),
Hugo can do [Zola-style blocks](https://gohugo.io/templates/base/),
but it's hard to figure this out on your own.
If you want to reuse a snippet, you typically put it in a file e.g. `navbar.html`
and include it as `{% raw %}{{ partial "navbar.html" . }}{% endraw %}`.
Note the dot at the end... I'll get to that.
Overall, Hugo's template organization feels "dumber" than Zola's,
although my requirements had become a lot more complicated by then.
Like most SSGs, Hugo uses an external template engine,
namely the [`text/template`](https://pkg.go.dev/text/template) Go package.
Disclaimer: I'm not a Go developer, so I don't know how nice this library is for various use-cases;
here I'm just reviewing whether it's good for HTML templates in Hugo.
Okay, here comes my review: it's awful. No, it isn't a good fit here:
the whole point of an SSG is to have a pretty sophisticated template language
to avoid needing to program a custom solution.
This package is just too primitive,
so Hugo has shoehorned all sorts of extensions into it to make it usable;
the result is an opaque mess with still too little flexibility.
For simple stuff like inserting the site's title somewhere it's fine,
but I need some pretty non-trivial templates.
To give you a taste, consider the following snippet I wrote,
which lists the 10 most recent articles from newest to oldest,
as seen on my knowledge base' [front page](/know/):
```html
{% raw %}<p>Most recent articles:
<ol>
{{ $concepts := where .RegularPagesRecursive "File.Dir" ">" "know/concept/" }}
{{ range first 10 $concepts.ByPublishDate.Reverse }}
<li><a href="{{ .RelPermalink }}">{{ .Title | title }}</a></li>
{{ end }}
</ol>
</p>{% endraw %}
```
This example captures the messiness of Hugo templates.
But on a more serious note,
there are some questionable design decisions here,
in no particular order:
* `.Title` is a variable, whose value is implicitly set by the surrounding `range` loop.
And what if you want to insert *this* page's title?
You also write `.Title`, just not inside a loop.
So you don't know what some variables contain,
unless you pay close attention to the context:
you need to be aware that this is happening inside a loop over an array of pages...
and not, of course, an array of something else,
so don't forget to type-check the loop.
To be fair, what's going on here is clearly explained
[in the docs](https://gohugo.io/templates/introduction/#the-dot):
the initial dot refers to the current context,
of which `Title` is an attribute.
The keywords `range` and `with` swap out the context from under your feet,
which I insist is bad design.
If you need the global context, it can always be accessed explicitly using `$.`,
so at least there's that?
* Meanwhile, `.ByPublishDate` is a function that sorts a list of pages;
specifically, it's a *method* in the object-oriented sense.
Okay, this works, but why did they add this feature,
instead of just telling us to use the more general
[`sort`](https://gohugo.io/functions/sort/) function?
`.Reverse` is another method, which flips the order of an array.
I have the same question: why this, instead of a general `reverse` function?
As of writing, no such function exists,
so if you want to reverse an array... [have fun](https://discourse.gohugo.io/t/reverse-array/28753).
This awkward split between methods and "normal" functions
makes it unclear how things can be composed.
Clearly, you can chain methods as `$xs.ByPublishDate.Reverse`,
or pipeline functions as `$x | title | sha256`,
but how do you mix the two?
And what if we need to pass additional arguments,
e.g. for [`.Param`](https://gohugo.io/functions/param/)
or [`hmac`](https://gohugo.io/functions/hmac/) (WTF, this SSG can do crypto)?
I'm sure there exist answers to these questions;
my point is that it's unnecessarily confusing.
* Nitpick: for looping over an array,
why did the Go developers choose the keyword `range`,
instead of `for` like almost all other computer languages?
To me, `range` is a function (like in Python),
and the order of `range first 10 xs` hence looks weird (coming from Haskell).
And why do [Hugo's docs](https://gohugo.io/functions/range/)
claim that `range` is indeed a function,
while the Go [package docs](https://pkg.go.dev/text/template#hdr-Actions)
clearly say that it's an *action*?
Documentation should be precise!
Maybe, if you're a Go/Hugo veteran, this all just makes sense to you
(then I'm both jealous and scared of you).
I just want you to keep my comments in mind
when I compare the same piece of templating code in the next SSG.
### Review
I don't mean to shame Hugo's developers with my complaints.
I suspect it started as a private experiment
(which would explain their choice of Go's template package for quick development)
that became too popular too fast.
Looking at [Jamstack's ranking](https://jamstack.org/generators/) of SSGs,
we see that Hugo is the only compiled program anywhere near the top,
and I think that explains its popularity:
there are a lot of performance-focused programmers out there,
who don't want an SSG in an interpreted language like JS or Python.
So when Hugo was released, it quickly attracted many users,
and also many contributors wanting various features.
The result is its current messy feel.
But for all my complaining, Hugo's popularity is a big advantage,
with many tutorials available online in addition
to the extensive official documentation.
And, as it claims, Hugo is indeed fast and flexible.
In practice, you only really interact with an SSG when writing your templates,
and after that most of your time is spent on actual content,
so although Hugo may sometimes get in your way during development,
it might not be a problem for you.
Towards the end of 2022, my maths rendering solution required
fetching 450KB of compressed JS on page load,
leading to a visible delay, which I wasn't happy with.
I'd discovered it was possible to render maths offline,
so no JS would need to be loaded,
but this couldn't reasonably be done with Hugo,
unless I forked it like [this guy](https://graemephi.github.io/posts/server-side-katex-with-hugo-part-2/)
did... No thanks.
It was time to change.
## Jekyll
Compared to Zola and Hugo,
[Jekyll's](https://jekyllrb.com/) feature set is fairly basic:
things like an automatic table of contents or multilingual pages
need to be added using plugins.
But on the upside it supports plugins at all,
thanks to being written in Ruby, an interpreted programming language,
unlike its compiled competitors.
It's quite mature compared to other popular SSGs,
and is what I'm using right now,
since I was able to get statically-rendered maths thanks to a plugin.
### Demonstration
At first sight, Jekyll's [Liquid](https://shopify.github.io/liquid/) templates
look very similar to Hugo's, due to its inclusion system:
```html
{% raw %}<html>
<head>
<title>{{ page.title }} | {{ site.title }}</title>
</head>
<body>
{% include navbar.html %}
{{ content }}
</body>
</html>{% endraw %}
```
But where did our table of contents go? For that, we need
the [`jekyll-toc`](https://github.com/toshimaru/jekyll-toc) extension
and pipe all our content through the `toc` filter.
Compared to Hugo, Jekyll has a trick up its sleeve here:
you can nest templates inside the `{% raw %}{{ content }}{% endraw %}` object.
So, let the above `default.html` be a skeleton for the actual page template,
which we then define as:
```html
{% raw %}---
layout: "default"
---
<div id="title">{{ page.title }}</div>
{{ content | toc }}{% endraw %}
```
Another template could be nested in `{% raw %}{{ content }}{% endraw %}`, and so on,
until the innermost block is filled with the converted Markdown,
which, unlike for Zola and Hugo, can also contain template code.
This approach is brilliant in my opinion: it's more flexible than Hugo
and needs less boilerplate than Zola.
Also, Jekyll doesn't try to guess which template should be used for what.
A standard feature of Markdown is that you can write HTML directly,
which gets copied verbatim while the rest is converted to HTML too.
A minor annoyance is that [kramdown](https://kramdown.gettalong.org/),
Jekyll's converter, insists on parsing the HTML I write,
but isn't very good at it:
for the image on [this page](/blog/2022/email-server-revisited/#motivation-1),
why did it generate a closing `</source>` tag?
That isn't valid! Fortunately, modern browsers are accustomed to this,
so it gets interpreted correctly anyway.
And what about my snippet to list the 10 most recent articles?
In Jekyll it looks [like this](/code/prefetch-jekyll/tree/source/know/index.md):
```html
{% raw %}{% assign concepts = site.pages | where_exp: "item", "item.layout == 'concept'" %}
{% assign newest = concepts | sort: "date" | reverse | slice: 0, 10 %}
<p>Most recent articles:
<ol>
{% for item in newest %}
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ol>
</p>{% endraw %}
```
There, isn't that much better?
Yes, it's a bit more verbose than Hugo,
but at least it's pretty clear what's going on;
with the documentation's help, you could write this yourself.
Now it's bearable for me to write complex templates...
although sometimes I maybe take it
[a bit too far](/code/prefetch-jekyll/tree/source/_includes/image.html).
### Review
Jekyll has been consistently popular for many years, and I can see why.
Its templating system is elegantly organized and flexible enough for most use-cases,
it's infinitely extensible with plugins
and plenty fast despite being written in Ruby.
Although 5 years older than Hugo, it doesn't feel nearly as messy.
Jekyll deserves some criticism for how it wants you to organize your files by default:
in both Zola and Hugo, you put your markdown into a dedicated `content` folder,
but in Jekyll you just dump it all directly into the root,
meaning that configuration and content aren't clearly separated, which I don't like.
Fortunately, you can fix this in `_config.yml` by setting `source`.
I'm happy with my choice to move to Jekyll,
and I don't want to do another migration ever again
(~200 files would need to be converted).
My site feels organized now,
and it builds in seconds, even including the process
of rendering all LaTeX maths into HTML.
In fact, I'm so satisfied that I've even published my
[source code](/code/prefetch-jekyll/tree/)!
## Conclusion
Making a functioning website isn't as hard as it seems,
but making a *good* one does take time.
Most of that time is spent writing HTML templates and especially CSS,
and realistically, both will need to be tweaked again and again over time.
But, in my humble opinion, it's worth the effort:
it's a constructive activity with tangible results.
I like seeing my work appear in a browser.
Do you want to build your own website using an SSG?
I recommend that you look at Zola first, with Jekyll a close second,
if you can deal with its higher complexity.
Personally, compared to those two, I wouldn't recommend Hugo,
but for some people (probably Go developers)
it just might be what they're looking for.
EDIT: There exists an SSG called [Soupault](https://soupault.app/)
that has interesting alternative take on site generation.
Its creator [pitched it to me](https://lobste.rs/s/x2bknz/adventures_making_my_website_static_site#c_cgemzs),
and coincidentally its website includes [this comparison](https://soupault.app/tips-and-tricks/comparison)
with the SSGs discussed in this article.
Like I said, I don't intend to migrate again, like, *ever*,
so I'm writing this to spread the word about an, in my opinion, intriguing project.
|
