Jekyll The Hard Way

Something there is in me that wants to scrape my knuckles raw, and hammer my thumbs, and porcupine my palms with splinters, before allowing me a good grasp on new knowledge.

The initial post on this site in November, 2024, declared a goal to use Jekyll and Liquid, a set of tools for making static web pages.

Leave it to me to approach it the hard way.

Sad experience with a so-called dynamic scheme movitated the desire to change. Dynamic pages get built by code running on a web server. Bad actors can inject clandestine code that corrupts the process, changing what goes out, with evil results.

Static web pages do not allow the web server to change what goes out. A server well-secured against unauthorized uploads may afford a safer place to host a web page.

I dumped all previous web content from my domain names and started over. New content to date has been written on my own computer, in text editors, as html code styled with css formatting instructions.

The resulting files are web-ready. I upload them to the Neocities server. To change or add content involves writing new work or revising existing work on my computer then uploading it.

As the number of pages increases for a given site, it becomes more tedious and complex to manage how the pages link to one another. Adding one new page typically requires revising links in other pages. It takes time. Finding and correcting inevitable mistakes takes even more time.

Jekyll can automate that part of the work. Here I come now, ten months later, finally learning how. A sibling web domain, GardenCat, returns to the Web that way after a multi-year absence.

What made it difficult? Ignorance, as usual, of course — compounded by bullheadedness.

Jekyll transforms a directory containing source files into another, different directory containing pages for a web site. Jekyll’s work is then complete. The user uploads the web page files onto a web server.

The source files are of two kinds. The first is plain text containing content that the user wants to display on the web. It need not be web-ready. Jekyll will transform each of the content files into a page for the web site.

The other kind comprises a set of configuration files, called a Theme. These files specify how Jekyll will turn content files into web pages. The Theme also determines how the pages will appear in a browser. In this way, a web site can present a consistent look and feel as visitors navigate through the pages.

After you add or revise a file of contents for a page, or modify one of the Theme files, Jekyll rebuilds all of the pages for the web site. This includes correctly updating links in older pages to take account of the new page.

It winds up giving the appearance of a dynamic web site while gaining the safety benefits of static files.

The Easy Way to use Jekyll is to accept a prepackaged Theme. For an example that costs no money to try, consider Github Pages. The tutorial there takes only a minute or two to complete. A starter Theme gets installed by default. At the time of writing, web hosting with Jekyll was available for free through Github, subject to certain limitations.

The Hard Way is to create your own Theme and to not use Github. See my sibling site, Code Diarist — The Documentation Challenge for more about the learning process.

I found it best to start by writing a set of html and css files for a working web site. Then I built backwards to construct a Jekyll theme that would produce the same site. A Jekyll tutorial proved helpful.

A week’s worth of time went into getting the first page to come out right. The result repays the effort, as adding more pages now takes almost no time at all.

I expect absolutely no one will bother to read all the way to the end here of this article. That is fine. The story is recorded for the benefit of my own recollection somewhere down the road.

Someone recently defined learning as a change in long-term memory. If that is true, then I will say The Hard Way teaches more effectively because the stones of Pain endure long after the flow of Time has washed the sand of Pleasure away.