Since I take a lot of notes, rcently I thought I could edit some of my notes and turn them into a blog. I wasn't satisfied with WordPress, because it's bloated. I didn't feel like to get familiar with the settings and configurations of other static site generators either. So I decided to write my own. I named it “Lysekil”, where I visited in late March and loved it there. I published it on GitHub and provided a brief documentation.

The color scheme used in the template was borrowed from the default “Red Graphite” theme of Bear, my favorite note-taking app. (It also happens to be Andy Matuschak's favorite note-taking app. I used to dither over a few other options, including Obsidian, RemNote and RoamResearch. In the end I would always come back to Bear.)

How I made it

I used third-party Python packages to process markdown, generate the Atom feed and highlight code syntax.

Markdown

Notes in Bear are in a plaintext format very similar to Markdown. Writing blogs in Markdown feels natural.

There are two Python packages available to convert Markdown files into HTML: python-markdown and python-markdown2.

I chose the latter because it allowed for eaiser integration with an extra that enables syntactic highlighting for code. It also seems easier to enable extras (or extension) in general with python-markdown2 than python-markdown.

Syntax highlighting

Both packages allow syntax highlighting using Pygments. It takes a lot more effort to enable code highlighting in python-markdown, according to their documentation.

With markdown2, I could enable “footnotes”[^1] and “fenced-code-blocks” extras with much ease. To my delight, the “fenched-code-blocks” work exactly the way highlighted code blocks work in Bear.

Feed

There are people on the web who call their personal websites blogs without providing an Atom or RSS feed. (I'm opinionated on this. It's not a blog if there's not a feed)

The package I used to create the Atom feed is python-feedgen. It does support both Atom and RSS. But there are tiny differences between the two. I chose Atom over RSS for no particular reason.

One hitch at this step was that Feedgen required timezone info to indicate the time of creation of entries. To make it work, we needed to pass this information using a timezone object.

This timezone object is defined in datetime package. One way you could specify a timezone prior to Python 3.9 was adding an offset to UTC using a timedelta.

Lucky for me, I've upgraded to Python 3.9.5, which provides a zoneinfo package that allows you to specify timezone info using a string, like this: ZoneInfo('Europe/Stockholm'). (The datetime package in Python 3.9.x also makes it easier to manipulate date and time in strings of ISO format.)

Blogs and pages

Blogs (or “notes”) are presented in chronological order and are organized with tags. They are grouped according to quarters of the year. Pages, on the other hand, are not presented in any timeline.

If you look at the source code, you'd see the implementation of this part is not particularly “DRY”.

Styling

I used SCSS to write the CSS sheetsheet. SCSS allowed nesting CSS selectors and that makes it a lot easier to organize your CSS file.

I tried adding animation effects for the header using JavaScript. I relied on window.onscroll event and it was a bad idea.

It did work on my MacBook Pro, iPhone and iPad. But because of the offset of scrolling on the y-axis and the difference between widths of shown elements, this doesn't work when the page is not long enough for certain screens.

When the page is not long enough, as the user scrolls up, there isn't an unambiguously large offset that triggers the change of width that can persist. Not to mention the (at least theoretical) performance issue caused by too many function calls as the page goes up. (This in itself can be talked about in more detail.)

I then tried using { position: sticky } to place the navigation bar on top of the article page. It did look nice. But since it's rather easy to navigate around here, letting the navigation bar take up too much space at the expense of reading experience didn't feel right. This was especially true on a smartphone.

What I did wrong

I began working on this SSG on a whim, without clearly planning out what functions I wanted and how I'd like to achieve them.

At the beginning I thought a single script that converted a bunch of .md files to HTML would do. I ended up with a template that consists of HTML code snippets sprinkled across six helper functions. (If anyone wants to create a new template for this SSG, I would recommend not to. LOL.)

To organize timelines, tags and archive groupings, I ended up creating two classes for content (notes and pages) and three classes for listings (tags, archive groupings and the home pagination). Had I planned it beforehand, with more proper inheritance, the classes would have looked DRY-er.

[^1]: Titta! Detta är en fotnot. (Look! This is a footnote.)

This is essentially how you emulate the way Python's zip() function works using JavaScript.

1let a = [1, 3, 5];
2let b = [2, 4, 6];
3const mapping = a.map((item, idx) => [item, b[idx]]);
4console.log(mapping);
5// result
6[ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ]

What makes this possible is the fact that JavaScript array methods — map(), forEach() and even filter() — take up to three arguments (element, index, array) while they iterate through the array.

In which element is the element that the iterator points to at each step, index is the index of this item in the original array. And it's worth noting the third argument is the original array.

Since map() method of the JavaScript array is more flexible than zip(), we can do more stuff to the iterated item or the array. But if you want to do anything with array, remember the original array changes accordingly. In this case, a:

 1let a = [1, 3, 5];
 2let b = [2, 4, 6];
 3const mapping = a.map((item, idx, array) => { 
 4    array.push(item*2);
 5    return [item, b[idx]]} );
 6console.log(mapping);
 7// Result
 8[ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ]
 9console.log(a);
10// Result
11[ 1, 3, 5, 2, 6, 10 ]

As we can see, integers 2, 6 and 10 are pushed to the end of the array.

Python provides a zip_longest() function in itertools.

While zip() cuts off longer lists to fit the shortest, zip_longest() stretches shorter lists to match the longest. Empty slots in shorter lists are filled with a given value. By default this fillvalue is None.

This is how this function works:

1import itertools
2
3a = [1, 3, 5, 7, 9]
4b = [-1, -3, -5]
5c = itertools.zip_longest(a, b)
6
7print(list(c))
8# Result
9[(1, -1), (3, -3), (5, -5), (7, None), (9, None)]

Below I try to emulate this function in JavaScript.

First let's take a look at line 👀. Notably, In order to take indefinite number of arguments, I'm using the ellipsis operator. Unlike unpacking a list using the star operator (*) in Python, using something like ...args, fillvalue=null will raise an error. So I have to use a pair of square brackets to allow for a fillvalue argument. (Let's give it a duck.)

 1let a = [5, 3, 1, -1, -3, -5]
 2let b = [6, 4, 2, 0, -2, -4, -6, -8]
 3let c = ['a', 'b', 'c', 'd']
 4
 5const zipLongest = ([...args], fillvalue=null) => {  👀
 6    const result = []
 7    let i=0
 8    while (args.some( argArray=> argArray[i])) {
 9        const ithColumn = args.map(
10            argArray=> {
11              item = (typeof argArray[i] === 'undefined')  👓
12              ? fillvalue
13              : argArray[i]
14              return item
15            }
16            )
17            result.push(ithColumn)
18            i++
19    }
20    return result
21}
22
23console.log(zipLongest([a, b, c], fillvalue="duck"))
24
25// Result
26[
27  [ 5, 6, 'a' ],
28  [ 3, 4, 'b' ],
29  [ 1, 2, 'c' ],
30  [ -1, 0, 'd' ],  🙄
31  [ -3, -2, 'duck' ],
32  [ -5, -4, 'duck' ],
33  [ 'duck', -6, 'duck' ],
34  [ 'duck', -8, 'duck' ]
35]

Then let's move to line 👓. Empty slots in the JavaScript array are considered undefined.

But undefined and other falsy values, eg empty strings and 0, all evaluates to false. This will confused this ternary conditional. As a result we will get [ -1, undefined, 'd' ] on line 🙄.

A better way is to check the type of item as we iterate. However, a wrong way to do it is using typeof nonExistentValue === undefined.

Although the nonExistentValue is indeed not defined, typeof returns "undefined", which is a string. And this string is a string. It is by no means equal to the reserved word for non-existent things. Thus the condition we used on line 👓.