Most unintuitive thing was casting integer variables.
Once I got a variable out of an array, lines such as
(debug: item holds: {{item}} ) would output as expected:
(debug: item holds: 4 ).
But then any attempts to increment it resulted in [0].

Complicating troubleshooting was the advice to cast Liquid variables explicitly before math operations could be applied to them using
{% var = var | plus: 0 %}.
( I believe I found references to this requirement for both to Jekyll's implementation of Liquid and the official version of Liquid)

Eventually, I discovered the debug filter {% var | inspect %}, and found out that my item variable was actually a 1-element-long array containing the integer, and I had to access it with item[0] to get the first (and only) element.

Although it's really nice to output an array without any syntax indicating the internals of the background programming language, this made debugging this issue a really elaborate series of searches and hurdles. But I understand the design choice, and honestly (in the context of all you can do with Jekyll and Liquid) it's incredibly polished.

Sidenote for clarification: this is more a catalogue of bread-crumbs for me to remember this journey than it is a critique. And a reminder for me to come back and contribute documentation when I'm financially stable + have enough time to do it well.

I jumped into this website project with just a month's worth of HTML+CSS understanding, and this was the only issue I encountered with Jekyll.

Despite these growing pains, I really enjoyed the whole experience: it's incredibly elegant, powerful, and simple.

So where did I land with this integration + development journey?

An amazing place.

New posts need a very minimal amount of variables added to the top (Jekyll's "front matter" region) , then I can just focus on defining the main content of the new post, entirely omitting the HTML for the site's header, footer, and sidebar.

You can see the minimal HTML code I needed to make this post here:
https://github.com/gamepad-coder/gamepad-coder.github.io/blob/master/_Philosophy/1__PlanningTheSite.html

Notice how there's no code for the header, nor for the sidebar, nor for the footer. The unbaked code for this blog post doesn't even contain the code to create the splash screen topic card at the top of the post.

I defined those once, and now when I write a blog post, I just define the content in the main block of the page. Then Jekyll takes the HTML code for those minimal blog posts and wraps each one with all the bells and whistles and produces the finished page. It's kind of fantastic.

Once I have a new post written, Jekyll's templating wraps the rest of the HTML they all share in common (or conditionally request) around the central page block, and constructs a complete HTML page that is styled similarly to the rest of the Blog Site. This is awesome, because:

• It save a ton of time and work
  (and a TON of rework if I change a single thing
  and need that one change applied to every single page).


• It lets me have separate files for
  1. the blog structure,
  2. individual blog post content


• It saves a TON of time and work,
  really, it's incredible.

Similarly, I don't need to copy+paste the HTML formatting for each post header, nor do I need to manually add tags below each post: I've written a series of simple Liquid commands to generate the HTML for these, and call upon these utilities using Jekyll's {%include%} feature.

Any new #topic tags I include in a post are auto-magically added to the PostsByTopic.html page (along with automatically rendered post-previews under each tag).

All posts are automatically added to the PostsByTime.html page (again, totally hands-off, the templating and Liquid code do all the repetitive lifting here).

All I have to do is make a new post.html file,
write a few variables containing

• the name,
• the tags,
• the time written
• the blog #

I would have started playing with web design a long long time ago had I known about this sooner (and if I didn't have a plethora of tasks surrounding my large desktop-replacement hobby-project).

Overall, I love Jekyll and the Liquid Language in general. Jekyll is a really powerful way to separate core page content from repeated structures. It took a good while to set up this site ( divided pretty evenly between Jekyll experiments, CSS styling, and setting up the Windows Subsystem for Linux (WSL) ), but adding additional posts is extremely hands-off for me now.

Wordpress seems nice.

But I'm glad I decided to make a website from scratch.