Open Source Encore: Jekyll documentation improvements for Include/Exclude

While working on this very website, I have come to learn more about Jekyll and Liquid as a result of setting up GitHub Pages (the mechanism through which the site is hosted) and using Liquid to generate the landing page with the list of contents that are available on the site.

I haven’t quite learn enough, though, in a sense, because while I did learn that GitHub Pages ships with an outdated version of Jekyll and Liquid (see the page for information - both are one major version behind), I wasn’t sure whether the exclude option I had added to _config.yml to tell Jekyll to include index.html (and thus “nested” GitHub Pages) in the submodules that make up the contents of the site would replace or augment the default exclusion list in Jekyll.

I turned to the Jekyll documentation site for answers and when I couldn’t get any, to the Jekyll repository where I posted this issue:

A helpful maintainer came back and explained that in Jekyll 3, the exclusion list is replaced whereas in Jekyll 4, it is appended to via this configuration option.

This way a slightly unfortunate information for me to learn as I was hoping for the Jekyll 4 behavior (which makes sense to me) to be what is going to happen on GitHub Pages, but that uses Jekyll 3 so I will need to add the default exclusion list to my _config.yml to make sure I don’t inadvertedly include something in my build I didn’t mean to when I added that custom exclude line.

In any case, this answer I felt was worth capturing in the Jekyll documentation so I set out to do just that.

I cloned the Jekyll repository and followed the steps outlined by the maintainer in his comment on my issue. Later on I’ve learnt they were helping me out by quoting bits of the macOS set up guide at as I was coming across issues this guide explains how to fix:

The backing file for this page is docs/_docs/configuration/ but it uses data from docs/_data/config_options/global.yml so I opened that file and pretty much just adjusted the HTML there with my prose.

Saving the files automatically reloads the page in the browser as expected so testing everything was fine was super easy.

After I was satistied with my changes, I opened a PR to the Jekyll project to solve the issue I’ve originally raised: