-
Notifications
You must be signed in to change notification settings - Fork 5
Expand file tree
/
Copy pathhow_to_make_your_own_static_site_generator.html
More file actions
698 lines (675 loc) · 69.2 KB
/
how_to_make_your_own_static_site_generator.html
File metadata and controls
698 lines (675 loc) · 69.2 KB
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
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
<!--
This file has been auto-generated by main.rs from a markdown file of the same name.
Do not edit it by hand.
-->
<!DOCTYPE html>
<html>
<head>
<title>How to make your own static site generator</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link type="application/atom+xml" href="/blog/feed.xml" rel="self">
<link rel="shortcut icon" type="image/ico" href="/blog/favicon.ico">
<link rel="stylesheet" type="text/css" href="main.css">
<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.8.0/styles/default.min.css">
<script type="module" src="main.js" async></script>
<script type="module" src="search.js" async></script>
</head>
<body>
<div id="banner">
<div id="name">
<img id="me" src="me.jpeg">
<span>Philippe Gaultier</span>
</div>
<input id="search" placeholder="🔎 Search" autocomplete=off>
<ul>
<li> <button id="dark-light-mode">Dark/Light</button> </li>
<li> <a href="/blog/body_of_work.html">Body of work</a> </li>
<li> <a href="/blog/articles-by-tag.html">Tags</a> </li>
<li> <a href="https://github.com/gaultier/resume/raw/master/Philippe_Gaultier_resume_en.pdf">
Resume
</a> </li>
<li> <a href="/blog/feed.xml">
<svg viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.5 3.5C4.39543 3.5 3.5 4.39543 3.5 5.5V18.5C3.5 19.6046 4.39543 20.5 5.5 20.5H18.5C19.6046 20.5 20.5 19.6046 20.5 18.5V5.5C20.5 4.39543 19.6046 3.5 18.5 3.5H5.5ZM7 19C8.10457 19 9 18.1046 9 17C9 15.8954 8.10457 15 7 15C5.89543 15 5 15.8954 5 17C5 18.1046 5.89543 19 7 19ZM6.14863 10.5052C6.14863 10.0379 6.52746 9.65906 6.99478 9.65906C7.95949 9.65906 8.91476 9.84908 9.80603 10.2183C10.6973 10.5874 11.5071 11.1285 12.1893 11.8107C12.8715 12.4929 13.4126 13.3027 13.7817 14.194C14.1509 15.0852 14.3409 16.0405 14.3409 17.0052C14.3409 17.4725 13.9621 17.8514 13.4948 17.8514C13.0275 17.8514 12.6486 17.4725 12.6486 17.0052C12.6486 16.2627 12.5024 15.5275 12.2183 14.8416C11.9341 14.1556 11.5177 13.5324 10.9927 13.0073C10.4676 12.4823 9.84437 12.0659 9.15842 11.7817C8.47246 11.4976 7.73726 11.3514 6.99478 11.3514C6.52746 11.3514 6.14863 10.9725 6.14863 10.5052ZM7 5.15385C6.53268 5.15385 6.15385 5.53268 6.15385 6C6.15385 6.46732 6.53268 6.84615 7 6.84615C8.33342 6.84615 9.65379 7.10879 10.8857 7.61907C12.1176 8.12935 13.237 8.87728 14.1799 9.82015C15.1227 10.763 15.8707 11.8824 16.3809 13.1143C16.8912 14.3462 17.1538 15.6666 17.1538 17C17.1538 17.4673 17.5327 17.8462 18 17.8462C18.4673 17.8462 18.8462 17.4673 18.8462 17C18.8462 15.4443 18.5397 13.9039 17.9444 12.4667C17.3491 11.0294 16.4765 9.72352 15.3765 8.6235C14.2765 7.52349 12.9706 6.65091 11.5333 6.05558C10.0961 5.46026 8.55566 5.15385 7 5.15385Z" fill="currentColor"/>
</svg>
</a> </li>
<li> <a href="https://www.linkedin.com/in/philippegaultier/">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" data-supported-dps="24x24" fill="currentColor" width="24" height="24" focusable="false">
<path d="M20.5 2h-17A1.5 1.5 0 002 3.5v17A1.5 1.5 0 003.5 22h17a1.5 1.5 0 001.5-1.5v-17A1.5 1.5 0 0020.5 2zM8 19H5v-9h3zM6.5 8.25A1.75 1.75 0 118.3 6.5a1.78 1.78 0 01-1.8 1.75zM19 19h-3v-4.74c0-1.42-.6-1.93-1.38-1.93A1.74 1.74 0 0013 14.19a.66.66 0 000 .14V19h-3v-9h2.9v1.3a3.11 3.11 0 012.7-1.4c1.55 0 3.36.86 3.36 3.66z"/>
</svg>
</a> </li>
<li> <a href="https://github.com/gaultier">
<svg height="32" aria-hidden="true" viewBox="0 0 24 24" version="1.1" width="32" data-view-component="true" fill="currentColor">
<path d="M12.5.75C6.146.75 1 5.896 1 12.25c0 5.089 3.292 9.387 7.863 10.91.575.101.79-.244.79-.546 0-.273-.014-1.178-.014-2.142-2.889.532-3.636-.704-3.866-1.35-.13-.331-.69-1.352-1.18-1.625-.402-.216-.977-.748-.014-.762.906-.014 1.553.834 1.769 1.179 1.035 1.74 2.688 1.25 3.349.948.1-.747.402-1.25.733-1.538-2.559-.287-5.232-1.279-5.232-5.678 0-1.25.445-2.285 1.178-3.09-.115-.288-.517-1.467.115-3.048 0 0 .963-.302 3.163 1.179.92-.259 1.897-.388 2.875-.388.977 0 1.955.13 2.875.388 2.2-1.495 3.162-1.179 3.162-1.179.633 1.581.23 2.76.115 3.048.733.805 1.179 1.825 1.179 3.09 0 4.413-2.688 5.39-5.247 5.678.417.36.776 1.05.776 2.128 0 1.538-.014 2.774-.014 3.162 0 .302.216.662.79.547C20.709 21.637 24 17.324 24 12.25 24 5.896 18.854.75 12.5.75Z"/>
</svg>
</a> </li>
<li> <a href="https://hachyderm.io/@pg">
<svg width="75" height="79" viewBox="0 0 75 79" xmlns="http://www.w3.org/2000/svg" fill="currentColor">
<path d="M73.8393 17.4898C72.6973 9.00165 65.2994 2.31235 56.5296 1.01614C55.05 0.797115 49.4441 0 36.4582 0H36.3612C23.3717 0 20.585 0.797115 19.1054 1.01614C10.5798 2.27644 2.79399 8.28712 0.904997 16.8758C-0.00358524 21.1056 -0.100549 25.7949 0.0682394 30.0965C0.308852 36.2651 0.355538 42.423 0.91577 48.5665C1.30307 52.6474 1.97872 56.6957 2.93763 60.6812C4.73325 68.042 12.0019 74.1676 19.1233 76.6666C26.7478 79.2728 34.9474 79.7055 42.8039 77.9162C43.6682 77.7151 44.5217 77.4817 45.3645 77.216C47.275 76.6092 49.5123 75.9305 51.1571 74.7385C51.1797 74.7217 51.1982 74.7001 51.2112 74.6753C51.2243 74.6504 51.2316 74.6229 51.2325 74.5948V68.6416C51.2321 68.6154 51.2259 68.5896 51.2142 68.5661C51.2025 68.5426 51.1858 68.522 51.1651 68.5058C51.1444 68.4896 51.1204 68.4783 51.0948 68.4726C51.0692 68.4669 51.0426 68.467 51.0171 68.4729C45.9835 69.675 40.8254 70.2777 35.6502 70.2682C26.7439 70.2682 24.3486 66.042 23.6626 64.2826C23.1113 62.762 22.7612 61.1759 22.6212 59.5646C22.6197 59.5375 22.6247 59.5105 22.6357 59.4857C22.6466 59.4609 22.6633 59.4391 22.6843 59.422C22.7053 59.4048 22.73 59.3929 22.7565 59.3871C22.783 59.3813 22.8104 59.3818 22.8367 59.3886C27.7864 60.5826 32.8604 61.1853 37.9522 61.1839C39.1768 61.1839 40.3978 61.1839 41.6224 61.1516C46.7435 61.008 52.1411 60.7459 57.1796 59.7621C57.3053 59.7369 57.431 59.7154 57.5387 59.6831C65.4861 58.157 73.0493 53.3672 73.8178 41.2381C73.8465 40.7606 73.9184 36.2364 73.9184 35.7409C73.9219 34.0569 74.4606 23.7949 73.8393 17.4898Z"/>
<path d="M61.2484 27.0263V48.114H52.8916V27.6475C52.8916 23.3388 51.096 21.1413 47.4437 21.1413C43.4287 21.1413 41.4177 23.7409 41.4177 28.8755V40.0782H33.1111V28.8755C33.1111 23.7409 31.0965 21.1413 27.0815 21.1413C23.4507 21.1413 21.6371 23.3388 21.6371 27.6475V48.114H13.2839V27.0263C13.2839 22.7176 14.384 19.2946 16.5843 16.7572C18.8539 14.2258 21.8311 12.926 25.5264 12.926C29.8036 12.926 33.0357 14.5705 35.1905 17.8559L37.2698 21.346L39.3527 17.8559C41.5074 14.5705 44.7395 12.926 49.0095 12.926C52.7013 12.926 55.6784 14.2258 57.9553 16.7572C60.1531 19.2922 61.2508 22.7152 61.2484 27.0263Z" fill="#928374" />
<defs>
<linearGradient id="paint0_linear_549_34" x1="37.0692" y1="0" x2="37.0692" y2="79" gradientUnits="userSpaceOnUse">
<stop stop-color="#6364FF"/>
<stop offset="1" stop-color="#563ACC"/>
</linearGradient>
</defs>
</svg>
</a> </li>
<li> <a href="https://bsky.app/profile/pgaultier.bsky.social">
<svg fill="currentColor" viewBox="0 0 64 57" width="32" style="width: 32px; height: 28.5px;"><path d="M13.873 3.805C21.21 9.332 29.103 20.537 32 26.55v15.882c0-.338-.13.044-.41.867-1.512 4.456-7.418 21.847-20.923 7.944-7.111-7.32-3.819-14.64 9.125-16.85-7.405 1.264-15.73-.825-18.014-9.015C1.12 23.022 0 8.51 0 6.55 0-3.268 8.579-.182 13.873 3.805ZM50.127 3.805C42.79 9.332 34.897 20.537 32 26.55v15.882c0-.338.13.044.41.867 1.512 4.456 7.418 21.847 20.923 7.944 7.111-7.32 3.819-14.64-9.125-16.85 7.405 1.264 15.73-.825 18.014-9.015C62.88 23.022 64 8.51 64 6.55c0-9.818-8.578-6.732-13.873-2.745Z"/></svg>
</a> </li>
</ul>
</div>
<div id="search-matches" hidden>
</div>
<div id="pseudo-body">
<div class="article-prelude">
<p><a href="/blog"> ⏴ Back to all articles</a></p>
<p class="publication-date">Published on 2026-03-09. Last modified on 2026-03-15.</p>
</div>
<div class="article-title">
<h1>How to make your own static site generator</h1>
<div class="tags"> <a href="/blog/articles-by-tag.html#blog" class="tag">Blog</a> </div>
</div>
<details class="toc"><summary>Table of contents</summary>
<ul>
<li>
<a href="#list-all-articles">List all articles</a>
</li>
<li>
<a href="#parsing">Parsing</a>
</li>
<li>
<a href="#linting">Linting</a>
</li>
<li>
<a href="#generate-the-table-of-content">Generate the table of content</a>
</li>
<li>
<a href="#generate-the-html">Generate the HTML</a>
</li>
<li>
<a href="#generate-the-rss-atom-feed">Generate the RSS/Atom feed</a>
</li>
<li>
<a href="#line-numbers-in-code-snippets">Line numbers in code snippets</a>
</li>
<li>
<a href="#generate-the-home-page">Generate the home page</a>
</li>
<li>
<a href="#search">Search</a>
</li>
<li>
<a href="#drafts">Drafts</a>
</li>
<li>
<a href="#live-reloading">Live reloading</a>
</li>
<li>
<a href="#caching-and-performance">Caching and performance</a>
</li>
<li>
<a href="#light-dark-mode">Light & Dark mode</a>
</li>
<li>
<a href="#conclusion">Conclusion</a>
</li>
</ul>
</details>
<p><em>Discussions: <a href="https://lobste.rs/s/qnnok5/how_make_your_own_static_site_generator">lobsters</a> .</em></p>
<p>I developed my <a href="https://github.com/gaultier/blog/blob/master/src/main.rs">own</a> static site generator for this blog. Initially it was just a Makefile. Over the years it evolved quite a bit.</p>
<p>At some point it took several seconds. Now it takes ~120 ms for a clean build and ~50 ms for an incremental build.</p>
<p>This is my lessons learned.</p>
<p>At its core, a static site generator typically must perform these steps:</p>
<pre>
<div class="code-header">
<span>Plaintext</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-plaintext"><span class="line-number"></span><span class="code-hl">read header.html</span>
<span class="line-number"></span><span class="code-hl">read footer.html </span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">get the list of all articles</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">for each article:</span>
<span class="line-number"></span><span class="code-hl"> parse article</span>
<span class="line-number"></span><span class="code-hl"> lint content</span>
<span class="line-number"></span><span class="code-hl"> generate table of content </span>
<span class="line-number"></span><span class="code-hl"> generate html</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">generate rss feed</span>
<span class="line-number"></span><span class="code-hl">generate home page</span>
</code></pre>
<p>The first version was this Makefile:</p>
<pre>
<div class="code-header">
<span>Makefile</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-makefile"><span class="line-number"></span><span class="code-hl">%.html: %.md header.html footer.html</span>
<span class="line-number"></span><span class="code-hl"> cat header.html >> $@</span>
<span class="line-number"></span><span class="code-hl"> pandoc --toc $< >> $@</span>
<span class="line-number"></span><span class="code-hl"> cat footer.html >> $@</span>
</code></pre>
<p>It did not have a RSS/Atom feed, no search, no tags, no linting, the home page listing articles was manually kept in sync, and it was slower than my current custom-grown generator!</p>
<h2 id="list-all-articles">
<a class="title" href="#list-all-articles">List all articles</a>
<a class="hash-anchor" href="#list-all-articles" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>I wrote about it <a href="/blog/making_my_static_blog_generator_11_times_faster.html">before</a>. The easiest way is to list files on the file system, but if you want accurate 'created' and 'last modified' dates for each article, especially when working from multiple computers, you probably will have to query <code>git</code> (short of using a full-on database).</p>
<p>The lesson learned here is that for performance, avoid the N+1 query trap. Do one command for all articles, instead of one for each:</p>
<pre>
<div class="code-header">
<span>Shell</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-shell"><span class="line-number"></span><span class="code-hl">$ git log --format='%aI' --name-status --no-merges --diff-filter=AMDR --reverse '*.md'</span>
</code></pre>
<p>The output of that one command is large, but it contains everything needed, and the overhead of process spawning is surpringly big, so spawning N processes is to be avoided at all costs.</p>
<p>Once in a while, cleaning up is a good idea to improve Git's performance:</p>
<pre>
<div class="code-header">
<span>Shell</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-shell"><span class="line-number"></span><span class="code-hl">$ git gc --aggressive --prune=now</span>
</code></pre>
<p>I am considering adding this command as a cron job on my computer, or as a background job in my generator.</p>
<h2 id="parsing">
<a class="title" href="#parsing">Parsing</a>
<a class="hash-anchor" href="#parsing" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>Chances are, you are authoring content in markdown or similar, which then must be converted to HTML. Even if you <em>are</em> writing HTML directly, this content needs to be post-processed quite a bit and thus must be parsed in the first place. No one wants to wrangle strings; structured data is the way to go.</p>
<p>I recommend using a library (or write your own) to parse the article, for example markdown, and this library <em>must</em> return Abstract Syntax Tree (AST). Since rich text is hierarchical, it is indeed best represented as a tree. Think of a hyperlink in a table cell, or a bold text in a list element. These are trees.</p>
<p>Another reason to work on the AST is that you have total control on the HTML generation, including for code blocks. This opens the door to syntax highlighting at generation time.</p>
<p>Currently, I implement syntax highlighting with JavaScript at runtime, but I may change this in the future. At least I have the ability to do it at build time.</p>
<p>If the content is huge, a search index might be required to be built. Having the AST is great to only index text and skip code blocks, inline HTML, etc.</p>
<h2 id="linting">
<a class="title" href="#linting">Linting</a>
<a class="hash-anchor" href="#linting" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>The linting step is much easier to implement on the AST. Here are a few examples of lints I have implemented:</p>
<ul>
<li>Detect invalid links, e.g. linking to a markdown article, where it should be pointing to the HTML version for it.</li>
<li><p>Code snippets without an explicit language declared, or an unknown language (this matters for syntax highlighting). E.g. these are invalid:</p>
<pre>
<div class="code-header">
<span>Markdown</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-markdown"><span class="line-number"></span><span class="code-hl"> ```</span>
<span class="line-number"></span><span class="code-hl"> foo := bar()</span>
<span class="line-number"></span><span class="code-hl"> ```</span>
</code></pre>
<pre>
<div class="code-header">
<span>Markdown</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-markdown"><span class="line-number"></span><span class="code-hl"> ```g0</span>
<span class="line-number"></span><span class="code-hl"> foo := bar()</span>
<span class="line-number"></span><span class="code-hl"> ```</span>
</code></pre>
<p>And this is valid:</p>
<pre>
<div class="code-header">
<span>Markdown</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-markdown"><span class="line-number"></span><span class="code-hl"> ```go</span>
<span class="line-number"></span><span class="code-hl"> foo := bar()</span>
<span class="line-number"></span><span class="code-hl"> ```</span>
</code></pre>
</li>
<li>Style: Prefer <code>1 KiB</code> over other variants e.g. <code>1 kb</code>, <code>1 KB</code>, <code>1 K</code>, etc</li>
<li>Forbid titles that skip a level, for example <code>h2 -> h4</code>. This is subjective, perhaps some people like to have this ability - I don't, so I prevent it.</li>
</ul>
<p>Other lints that could be also easily implemented based on walking the AST:</p>
<ul>
<li>Forbid lists with only one element</li>
<li>Inline code elements whose content exceeds a certain length; these should be use the syntax for a multiline code block</li>
<li>Forbid images without an <code>alt</code> attribute for accessibility</li>
<li>Forbid media (images, audio, video) without fallback format(s)</li>
</ul>
<h2 id="generate-the-table-of-content">
<a class="title" href="#generate-the-table-of-content">Generate the table of content</a>
<a class="hash-anchor" href="#generate-the-table-of-content" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>This also relies on the AST: I collect all title elements, including their depth and text content. Then, I insert at the beginning of the article the table of contents.</p>
<p>These titles:</p>
<pre>
<div class="code-header">
<span>Markdown</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-markdown"><span class="line-number"></span><span class="code-hl">## Foo</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">### Bar</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">## Baz</span>
</code></pre>
<p>Get collected into this array, conceptually:</p>
<pre>
<div class="code-header">
<span>Json</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-json"><span class="line-number"></span><span class="code-hl">[</span>
<span class="line-number"></span><span class="code-hl"> {</span>
<span class="line-number"></span><span class="code-hl"> "title": "Foo",</span>
<span class="line-number"></span><span class="code-hl"> "depth": 2</span>
<span class="line-number"></span><span class="code-hl"> },</span>
<span class="line-number"></span><span class="code-hl"> {</span>
<span class="line-number"></span><span class="code-hl"> "title": "Bar",</span>
<span class="line-number"></span><span class="code-hl"> "depth": 3</span>
<span class="line-number"></span><span class="code-hl"> },</span>
<span class="line-number"></span><span class="code-hl"> {</span>
<span class="line-number"></span><span class="code-hl"> "title": "Baz",</span>
<span class="line-number"></span><span class="code-hl"> "depth": 2</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl">]</span>
</code></pre>
<p>And that gets turned into this HTML, which is just nested lists with links:</p>
<pre>
<div class="code-header">
<span>Html</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-html"><span class="line-number"></span><span class="code-hl"><ul></span>
<span class="line-number"></span><span class="code-hl"> <li></span>
<span class="line-number"></span><span class="code-hl"> <a href="/Foo">Foo</a></span>
<span class="line-number"></span><span class="code-hl"> <ul></span>
<span class="line-number"></span><span class="code-hl"> <li></span>
<span class="line-number"></span><span class="code-hl"> <a href="/Bar">Bar</a></span>
<span class="line-number"></span><span class="code-hl"> </li></span>
<span class="line-number"></span><span class="code-hl"> </ul></span>
<span class="line-number"></span><span class="code-hl"> </li></span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> <li></span>
<span class="line-number"></span><span class="code-hl"> <a href="/Baz">Baz</a></span>
<span class="line-number"></span><span class="code-hl"> </li></span>
<span class="line-number"></span><span class="code-hl"></ul></span>
</code></pre>
<p>The only interesting thing about this code is that it performs a linear scan of all titles in the article, which are stored in a flat array. In the past I used to build a tree of the titles, but it's unnecessary, slower, allocates more, and honestly not really more readable:</p>
<pre>
<div class="code-header">
<span>Rust</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-rust"><span class="line-number"></span><span class="code-hl">struct Title {</span>
<span class="line-number"></span><span class="code-hl"> text: String,</span>
<span class="line-number"></span><span class="code-hl"> depth: u8,</span>
<span class="line-number"></span><span class="code-hl"> start_md_offset: usize,</span>
<span class="line-number"></span><span class="code-hl"> slug: String,</span>
<span class="line-number"></span><span class="code-hl">}</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">fn md_render_toc(content: &mut Vec<u8>, titles: &[Title]) {</span>
<span class="line-number"></span><span class="code-hl"> if titles.is_empty() {</span>
<span class="line-number"></span><span class="code-hl"> return;</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> writeln!(</span>
<span class="line-number"></span><span class="code-hl"> content,</span>
<span class="line-number"></span><span class="code-hl"> r#" <details class="toc"><summary>Table of contents</summary></span>
<span class="line-number"></span><span class="code-hl"><ul>"#</span>
<span class="line-number"></span><span class="code-hl"> )</span>
<span class="line-number"></span><span class="code-hl"> .unwrap();</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> let mut current_depth = titles[0].depth;</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> for (i, title) in titles.iter().enumerate() {</span>
<span class="line-number"></span><span class="code-hl"> if title.depth > current_depth {</span>
<span class="line-number"></span><span class="code-hl"> for _ in 0..(title.depth - current_depth) {</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "<ul>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> } else if title.depth < current_depth {</span>
<span class="line-number"></span><span class="code-hl"> // Close the current <li>, then close the <ul> levels, then close the parent <li>.</span>
<span class="line-number"></span><span class="code-hl"> for _ in 0..(current_depth - title.depth) {</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "</li>\n</ul>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "</li>").unwrap(); // Close the <li> of the previous same-level item.</span>
<span class="line-number"></span><span class="code-hl"> } else if i > 0 {</span>
<span class="line-number"></span><span class="code-hl"> // Same level: just close the previous item.</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "</li>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> current_depth = title.depth;</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> writeln!(</span>
<span class="line-number"></span><span class="code-hl"> content,</span>
<span class="line-number"></span><span class="code-hl"> r##"</span>
<span class="line-number"></span><span class="code-hl"> <li></span>
<span class="line-number"></span><span class="code-hl"> <a href="#{}">{}</a>"##,</span>
<span class="line-number"></span><span class="code-hl"> title.slug, &title.text,</span>
<span class="line-number"></span><span class="code-hl"> )</span>
<span class="line-number"></span><span class="code-hl"> .unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> // Final cleanup: close all remaining open tags.</span>
<span class="line-number"></span><span class="code-hl"> let base_depth = titles[0].depth;</span>
<span class="line-number"></span><span class="code-hl"> for _ in 0..=(current_depth - base_depth) {</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "</li>\n</ul>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> writeln!(content, "</details>\n").unwrap();</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>If the same title appears multiple times (in different sections), a counter (<code>1</code>, <code>2</code>, etc) is appended to the link so that each link is unique on the page. This <a href="/blog/making_my_debug_build_run_100_times_faster.html">article</a> is a good example.</p>
<p>Finally, a bit of CSS gets us section numbers before each title, e.g. <code>3.4.1</code>:</p>
<pre>
<div class="code-header">
<span>Css</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-css"><span class="line-number"></span><span class="code-hl">.toc ul { </span>
<span class="line-number"></span><span class="code-hl"> counter-reset: section;</span>
<span class="line-number"></span><span class="code-hl">}</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">.toc li::before {</span>
<span class="line-number"></span><span class="code-hl"> counter-increment: section;</span>
<span class="line-number"></span><span class="code-hl"> content: counters(section, ".") " ";</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<h2 id="generate-the-html">
<a class="title" href="#generate-the-html">Generate the HTML</a>
<a class="hash-anchor" href="#generate-the-html" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>I walk the AST and mechanically generate the appropriate HTML for each markdown element.</p>
<p>I have total freedom here, and can add our own CSS classes, ids, data attributes, etc.</p>
<p>It is also straightforward to adapt this code to generate other formats, e.g. Latex (if you enjoy that kind of thing), etc.</p>
<p>As previously mentioned this is where doing static syntax highlighting could take place.</p>
<p>The only things to watch for are:</p>
<ul>
<li>Escape special HTML chars (no need to be super defensive since this is our content, not arbitrary user generated content)</li>
<li>Footnotes need to be collected to list them at the end in the HTML.</li>
</ul>
<p>Here's an excerpt:</p>
<pre>
<div class="code-header">
<span>Rust</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-rust"><span class="line-number"></span><span class="code-hl">fn md_to_html_rec(</span>
<span class="line-number"></span><span class="code-hl"> content: &mut Vec<u8>,</span>
<span class="line-number"></span><span class="code-hl"> footnote_defs: &mut Vec<FootnoteDefinition>,</span>
<span class="line-number"></span><span class="code-hl"> node: &Node,</span>
<span class="line-number"></span><span class="code-hl"> titles: &[Title],</span>
<span class="line-number"></span><span class="code-hl"> inside_thead: bool,</span>
<span class="line-number"></span><span class="code-hl">) {</span>
<span class="line-number"></span><span class="code-hl"> match node {</span>
<span class="line-number"></span><span class="code-hl"> Node::InlineCode(inline_code) => {</span>
<span class="line-number"></span><span class="code-hl"> let sanitized = text_sanitize_for_html(&inline_code.value, false);</span>
<span class="line-number"></span><span class="code-hl"> write!(content, "<code>{}</code>", sanitized).unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> Node::Delete(delete) => {</span>
<span class="line-number"></span><span class="code-hl"> write!(content, "<del>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> for child in &delete.children {</span>
<span class="line-number"></span><span class="code-hl"> md_to_html_rec(content, footnote_defs, child, titles, false);</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> write!(content, "</del>").unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"> Node::Image(image) => {</span>
<span class="line-number"></span><span class="code-hl"> write!(</span>
<span class="line-number"></span><span class="code-hl"> content,</span>
<span class="line-number"></span><span class="code-hl"> r#"<img src="{}" alt="{}" />"#,</span>
<span class="line-number"></span><span class="code-hl"> image.url, image.alt</span>
<span class="line-number"></span><span class="code-hl"> )</span>
<span class="line-number"></span><span class="code-hl"> .unwrap();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> // [...]</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<h2 id="generate-the-rss-atom-feed">
<a class="title" href="#generate-the-rss-atom-feed">Generate the RSS/Atom feed</a>
<a class="hash-anchor" href="#generate-the-rss-atom-feed" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>I have written about it <a href="/blog/feed.html">before</a>. This is very simple, I just generate a XML file listing all articles including the creation and modification date. I use <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID v5</a> to assign an id to each article because it's a good fit: the blog itself has a UUID which is the namespace, and the UUID for each article is <code>sha1(blog_namespace + article_file_path)</code>.</p>
<p>I save the XML in the file <code>feed.xml</code> and mention this XML in the HTML in the <code><head></code> element:</p>
<pre>
<div class="code-header">
<span>Html</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-html"><span class="line-number"></span><span class="code-hl"><link type="application/atom+xml" href="/blog/feed.xml" rel="self"></span>
</code></pre>
<h2 id="line-numbers-in-code-snippets">
<a class="title" href="#line-numbers-in-code-snippets">Line numbers in code snippets</a>
<a class="hash-anchor" href="#line-numbers-in-code-snippets" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>Line numbers in code snippets are done entirely in CSS. Each line of the code snippet is preceded with an empty span with the CSS class <code>line-number</code>.</p>
<p>Then, I let the browser compute the right line number:</p>
<pre>
<div class="code-header">
<span>Css</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-css"><span class="line-number"></span><span class="code-hl">.line-number {</span>
<span class="line-number"></span><span class="code-hl"> user-select: none;</span>
<span class="line-number"></span><span class="code-hl">}</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">.line-number::before {</span>
<span class="line-number"></span><span class="code-hl"> counter-increment: line-count;</span>
<span class="line-number"></span><span class="code-hl"> content: counter(line-count);</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>Thanks to <code>user-select: none</code>, copy-pasting code works out of the box: the line numbers will not be part of the selection.</p>
<p>And to gain a bit of space, line numbers are not displayed on small screens:</p>
<pre>
<div class="code-header">
<span>Css</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-css"><span class="line-number"></span><span class="code-hl">@media only screen and (max-width: 650px) {</span>
<span class="line-number"></span><span class="code-hl"> .line-number { display: none; }</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<h2 id="generate-the-home-page">
<a class="title" href="#generate-the-home-page">Generate the home page</a>
<a class="hash-anchor" href="#generate-the-home-page" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>This is the <code>index.html</code>, typically. It generally lists all articles (in my case), or only the recent ones, or the most read. The only thing worth mentioning is that in my case, each article has manually defined tags, such as <code>Go</code>, <code>Rust</code>, etc. So this page shows the tags for each article, and there is also a <a href="/blog/articles-by-tag.html">page</a> showing articles by tags.</p>
<h2 id="search">
<a class="title" href="#search">Search</a>
<a class="hash-anchor" href="#search" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>To implement the search function which is purely client side, I used to have a search index with trigrams. However I realized that at my scale, a linear search is just fast enough (< 1ms), and it is not much data to transfer (3 MiB uncompressed for all articles, Github pages applies gzip compression automatically with a 2-10x compression ratio).</p>
<p>When someone types in the search box for the first time, the HTML content for each article is fetched in parallel. This way, users who never use the search feature do not pay the price for it. The browser caches future fetches. If a loyal reader already has read all articles, then they are already cached in their browser and the fetch is a no-op.</p>
<p>To avoid searching for irrelevant content, I ignore some DOM elements, e.g. the header, footer, code snippets, etc.</p>
<p>When a user types in the search box, the content of all articles is linearly searched with <code>indexOf()</code>. Since this function is very likely implemented with SIMD, it is lightning fast. Then, for each match, the link to the article, as well as surrounding text, is shown.</p>
<h2 id="drafts">
<a class="title" href="#drafts">Drafts</a>
<a class="hash-anchor" href="#drafts" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>Some site generators have a <code>drafts</code> folder, or some metadata field at the beginning of the article e.g. <code>Draft: true</code>, to write an article that is not yet publicly accessible.</p>
<p>I just create a new Git branch when I want to write a new article. The new article is created and written as any other article.</p>
<p>Whenever the branch is merged, the article will appear on Github pages, which uses the files on the master branch.</p>
<p>I think that's just the easiest way to do it, the site generator does not need to model drafts in any way.</p>
<h2 id="live-reloading">
<a class="title" href="#live-reloading">Live reloading</a>
<a class="hash-anchor" href="#live-reloading" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>I always wanted to add live-reloading to have a nicer writing experience, which I'm convinced helps write more and better articles. The goal was to have the whole cycle take under 100 ms. Currently it takes ~50 ms which is great. Nearly all of this time is taken by Git to get the list of articles including the 'created at' and 'modified at' dates. Not much to optimize here, short of doing a manual <code>stat(2)</code> call to circumvent Git.</p>
<p>The way it works is, in the same process:</p>
<ol>
<li>At start-up, all articles are generated. This is a clean build (because the cache is not stored on disk and only exists in memory, it is empty at start-up) and takes ~120 ms on my machine.</li>
<li>An HTTP server is started. It serves static files and also has a <code>/live-reload</code> endpoint. It uses <a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">server-sent events (SSE)</a> to tell the client: hey, a file changed, reload the page.</li>
<li>A thread is spawned to watch the file system for changes. When a relevant file is changed, an event is broadcast to all listening threads (the SSE serving threads) with <code>cvar.notify_all()</code>. While no file is changed, the thread watching the file system is idle since it is blocked on a system call (<code>kqueue</code>, <code>inotify</code>, etc), and the SSE threads are also idle, waiting on the condition variable with <code>cvar.wait()</code>. That means 0% CPU consumption until a file is changed.</li>
</ol>
<p>The whole code for it is ~100 lines of code. It would be even less if I found a small HTTP server library that correctly handles SSE, without having to use complex asynchronous code. I implement SSE by hand, and since the format is super simple (newline delimited text events), it's not much work at all:</p>
<pre>
<div class="code-header">
<span>Rust</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-rust"><span class="line-number"></span><span class="code-hl">fn live_reload(</span>
<span class="line-number"></span><span class="code-hl"> mut resp: BufWriter<TcpStream>,</span>
<span class="line-number"></span><span class="code-hl"> mtx_cond: Arc<(Mutex<()>, Condvar)>,</span>
<span class="line-number"></span><span class="code-hl">) -> Result<(), ()> {</span>
<span class="line-number"></span><span class="code-hl"> write!(</span>
<span class="line-number"></span><span class="code-hl"> resp,</span>
<span class="line-number"></span><span class="code-hl"> "HTTP/1.1 200\r\nCache-Control: no-cache\r\nContent-Type: text/event-stream\r\n\r\n"</span>
<span class="line-number"></span><span class="code-hl"> )</span>
<span class="line-number"></span><span class="code-hl"> .map_err(|_| ())?;</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> loop {</span>
<span class="line-number"></span><span class="code-hl"> let (lock, cvar) = &*mtx_cond;</span>
<span class="line-number"></span><span class="code-hl"> let guard = lock.lock().map_err(|_| ())?;</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> drop(cvar.wait(guard).map_err(|_| ())?);</span>
<span class="line-number"></span><span class="code-hl"> write!(resp, "data: foobar\n\n").map_err(|_| ())?;</span>
<span class="line-number"></span><span class="code-hl"> resp.flush().map_err(|_| ())?;</span>
<span class="line-number"></span><span class="code-hl"> println!("🔃 sse event sent");</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>And the JavaScript side is also very short (this used to be longer but a friendly commenter posted a much shorter version!):</p>
<pre>
<div class="code-header">
<span>Javascript</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-javascript"><span class="line-number"></span><span class="code-hl">location.origin.includes("github") || (new EventSource("/blog/live-reload").onmessage = () => location.reload());</span>
</code></pre>
<p>The check means: I only try to live-reload locally, not when the page is served from Github pages.</p>
<p>SSE has a big advantage: The browser tries to reconnect automatically if the network connection goes away.</p>
<p>This works beautifully. A prior version used WebSockets and that proved to be a headache compared to SSE. If the flow of events is strictly unidirectional, from the server to the client, SSE is much simpler.</p>
<p><code>location.reload()</code> is a bit heavy-handed since it reloads the page completely. The nice thing is that every asset is reloaded including CSS, images, etc. However there is a visible flash when the page is being re-rendered.</p>
<p>A more advanced live reloading approach, which is also more work, is to tell the browser what changed exactly. If an asset file changed, reload the page. If the content changed, send the new content to the browser, and replace it in the DOM. This can be taken to the extreme by doing precise diffing and only replacing, say, the one character that changed.</p>
<p>Perhaps I'll consider doing that in the future.</p>
<h2 id="caching-and-performance">
<a class="title" href="#caching-and-performance">Caching and performance</a>
<a class="hash-anchor" href="#caching-and-performance" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>To avoid regenerating files that have not changed, I added a cache which is just a <code>Map<hash of inputs, generated output></code>.</p>
<p>In the case of a cache miss, when the work for an article is done, the output is stored in the cache.</p>
<p>If an input changed, then the hash is different, it's a cache miss, and the article will be regenerated. If the content for one article changed, only this article will have to be regenerated. If <code>header.html</code> or <code>footer.html</code> changed, then all articles will be regenerated, automatically.</p>
<pre>
<div class="code-header">
<span>Rust</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-rust"><span class="line-number"></span><span class="code-hl">#[derive(Clone)]</span>
<span class="line-number"></span><span class="code-hl">struct Article {</span>
<span class="line-number"></span><span class="code-hl"> git_stat: GitStat,</span>
<span class="line-number"></span><span class="code-hl"> html_title: String,</span>
<span class="line-number"></span><span class="code-hl"> html_path: PathBuf,</span>
<span class="line-number"></span><span class="code-hl"> tags: Vec<String>,</span>
<span class="line-number"></span><span class="code-hl"> html_output: Vec<u8>,</span>
<span class="line-number"></span><span class="code-hl">}</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">fn hash_article_inputs(html_header: &[u8], html_footer: &[u8], md_content: &[u8]) -> u64 {</span>
<span class="line-number"></span><span class="code-hl"> let mut hasher = DefaultHasher::new();</span>
<span class="line-number"></span><span class="code-hl"> html_header.hash(&mut hasher);</span>
<span class="line-number"></span><span class="code-hl"> html_footer.hash(&mut hasher);</span>
<span class="line-number"></span><span class="code-hl"> md_content.hash(&mut hasher);</span>
<span class="line-number"></span><span class="code-hl"> hasher.finish()</span>
<span class="line-number"></span><span class="code-hl">}</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">fn md_render_article(</span>
<span class="line-number"></span><span class="code-hl"> git_stat: GitStat,</span>
<span class="line-number"></span><span class="code-hl"> html_header: &[u8],</span>
<span class="line-number"></span><span class="code-hl"> html_footer: &[u8],</span>
<span class="line-number"></span><span class="code-hl"> cache: &mut HashMap<u64, Article>,</span>
<span class="line-number"></span><span class="code-hl">) -> Article {</span>
<span class="line-number"></span><span class="code-hl"> let md_content_bytes = fs::read(&git_stat.path_from_git_root).unwrap();</span>
<span class="line-number"></span><span class="code-hl"> let hash = Cache::hash(&html_header, &html_footer, &md_content_bytes);</span>
<span class="line-number"></span><span class="code-hl"> if let Some(article) = cache.get(&hash) {</span>
<span class="line-number"></span><span class="code-hl"> return article.clone();</span>
<span class="line-number"></span><span class="code-hl"> }</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> // [...] Do the work, write the HTML to the byte array `sb`.</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> let article = Article {</span>
<span class="line-number"></span><span class="code-hl"> git_stat,</span>
<span class="line-number"></span><span class="code-hl"> html_title: html_root_title,</span>
<span class="line-number"></span><span class="code-hl"> html_path,</span>
<span class="line-number"></span><span class="code-hl"> tags: tags.iter().map(|t| t.to_string()).collect(),</span>
<span class="line-number"></span><span class="code-hl"> html_output: sb,</span>
<span class="line-number"></span><span class="code-hl"> };</span>
<span class="line-number"></span><span class="code-hl"> cache.insert(hash, article.clone());</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl"> article</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>Technically I could use the <a href="https://docs.rs/nohash-hasher/0.2.0/nohash_hasher/">nohash</a> crate to optimize a bit, since the key in the map is already a hash, no need to hash it a second time. But I don't bother for now.</p>
<p>I never clear the cache, because my computer has so much memory. This has one advantage: if I undo a change when writing an article, and the work had already finished, I will hit the existing cache entry again. Crucially, all HTML files are written to disk every time, whether it was a cache hit or not. This is required to avoid the cache and the disk going out-of-sync.</p>
<p>Skipping all this work is fine for one reason only: generating the HTML for an article is a pure function with immutable arguments. If it mutated a variable (for example a search index), I could not easily skip this work.</p>
<p>This was an interesting lesson for me: no shared mutable variables (except the cache) makes parallel and incremental computations possible.</p>
<p>Right now I do not (yet) generate the HTML for each article in parallel, because it's already plenty fast, but conceptually I could, since each article is fully independent from the others (again, except for the cache).</p>
<p>Caching is I think a spectrum, some operations are so cheap and fast that caching them is not worth it. It can be taken to the extreme: <a href="https://salsa-rs.github.io/salsa/reference/algorithm.html#the-red-green-algorithm">Salsa</a>, <a href="https://buck.build/concept/what_makes_buck_so_fast.html">Buck</a>. In my experience, there is usually one main expensive operation in the system (in my case: Markdown parsing), and adding a cache in front of that is generally sufficient.</p>
<p>Finally, caching should not be a band-aid for general slowness. If some operation is unnecessarily slow, try to optimize it first, and ensure it is really needed. For example, I initially had the search index encoded as JSON, and it took ~600 ms to build and marshal it. I optimized it to only take ~10 ms. In the end, I realized I don't need a search index at all and removed all of this code. Do less, go faster.</p>
<p>This suprised me: in most cases, we all deal with data that's just not that big, and linear operations (array, linear scan), are often just fast enough, especially with SIMD and the CPU prefetcher.</p>
<h2 id="light-dark-mode">
<a class="title" href="#light-dark-mode">Light & Dark mode</a>
<a class="hash-anchor" href="#light-dark-mode" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>Modern CSS has proper support for light and dark mode with the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark">light-dark()</a> function.</p>
<p>This is enabled with:</p>
<pre>
<div class="code-header">
<span>Css</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-css"><span class="line-number"></span><span class="code-hl">body {</span>
<span class="line-number"></span><span class="code-hl"> color-scheme: light dark;</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>or</p>
<pre>
<div class="code-header">
<span>Javascript</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-javascript"><span class="line-number"></span><span class="code-hl">document.body.style['color-scheme'] = 'light dark';</span>
</code></pre>
<p>And used like this:</p>
<pre>
<div class="code-header">
<span>Css</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-css"><span class="line-number"></span><span class="code-hl">div {</span>
<span class="line-number"></span><span class="code-hl"> background: light-dark(#fbf1c7, #282828);</span>
<span class="line-number"></span><span class="code-hl"> color: light-dark(#282828, #fbf1c7);</span>
<span class="line-number"></span><span class="code-hl">}</span>
</code></pre>
<p>The first argument is the color in light mode, and the second argument the color in dark mode.</p>
<p>The browser detects the current mode if the OS supports that concept and sets the value for the page automatically. Then, it picks the right CSS color that was provided with <code>light-dark()</code>.</p>
<p>Light or dark mode can also be set manually (for example when the user clicks the light/dark mode button):</p>
<pre>
<div class="code-header">
<span>Javascript</span>
<button class="copy-code" type="button"><svg aria-hidden="true" focusable="false" class="octicon octicon-copy" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" display="inline-block" overflow="visible" style="vertical-align: text-bottom;"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button>
</div>
<code class="language-javascript"><span class="line-number"></span><span class="code-hl">console.log(document.body.style.colorScheme);</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">document.body.style.colorScheme = 'light';</span>
<span class="line-number"></span><span class="code-hl"></span>
<span class="line-number"></span><span class="code-hl">document.body.style.colorScheme = 'dark';</span>
</code></pre>
<p>Easy!</p>
<h2 id="conclusion">
<a class="title" href="#conclusion">Conclusion</a>
<a class="hash-anchor" href="#conclusion" aria-hidden="true" onclick="navigator.clipboard.writeText(this.href);"></a>
</h2>
<p>If you use an existing static site generator and you're satisfied, then great!</p>
<p>Otherwise, I hope I have shown that writing your own is not much work at all. All of it is ~1.5 kLoC. And it's a great way to experiment and learn new things, for example SSE, search index, etc.</p>
<p>At work I sometimes have to use <em>very</em> slow site generators, that take <em>minutes</em> to build, and I am left really confused. Modern computers can do a <em>lot</em> in just 1 second!</p>
<p>Something else that stroke me is how similar a static site generator is to a compiler: AST parsing, caching, linting, generate the output by walking the AST, etc.</p>
<p><a href="/blog"> ⏴ Back to all articles</a></p>
<div id="donate">
<em>
<p>If you enjoy what you're reading, you want to support me, and can afford it: <a href="https://paypal.me/philigaultier?country.x=DE&locale.x=en_US">Support me</a>. That allows me to write more cool articles!</p>
<p>
This blog is <a href="https://github.com/gaultier/blog">open-source</a>!
If you find a problem, please open a Github issue.
The content of this blog as well as the code snippets are under the <a href="https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_(%22BSD_License_2.0%22,_%22Revised_BSD_License%22,_%22New_BSD_License%22,_or_%22Modified_BSD_License%22)">BSD-3 License</a> which I also usually use for all my personal projects. It's basically free for every use but you have to mention me as the original author.
</p>
</em>
</div>
</div>
</body>
</html>