Bypassing GitHub's Jekyll limitations

As I feared when I migrated to GitHub’s hosting, it has become too complicated to overcome GitHub’s limitations on Jekyll plugins and features.

I just needed to create a collection to put my “live drafts” into it, but the deprecated jekyll-paginate plugin provided with GitHub pages didn’t support collections.

I therefore switched to offline-building my site and pushing the generated static files to GitHub, which now serves them without Jekyll processing. I still use Jekyll to generate the final static files, which is perfectly ok. The only thing I’m missing a bit is automatic build & deploy after a minor edit from my android smartphone (using Markor to edit and MGit to push to GitHub). It might be solved with some Travis CI automation I guess…

GitHub’s documentation about this is not very clear on the way one can still use an autonomous Jekyll installation to build offline, without them building the site with their locked-down Jekyll pipeline. I assumed that I had to consider the procedure that applied to other tools. I had to :

• create a .nojekyll file in the root of the repo
• change Jekyll’s output directory from _site to docs
• use the standard Jekyll dependencies in my Gemfile and specify the full list of plugins previously overwritten by github-pages in Gemfile & _config.yml
• import and commit the code for the submodule mastodon-timeline-widget inside this repo, not only leaving the .gitmodules file (static Javascript files that are used in the site, which were pulled automatically during GitHub’s processing)
• make sure a docs/CNAME text file containing the domain to serve is present after each build (I discovered it is created when the custom domain is enabled on GitHub ; unfortunately it is in the output docs/ directory, which may legitimately be deleted with a simple jekyll clean)
• I also had to change the name of the repo from nicolabs.github.io to nicolabs.net so it is not recognized as a user/organization repo, which was preventing me to put the code in a docs subdirectory (I already had an index.html which had to be processed by Jekyll in the repo’s root, and therefore the website’s root could not be placed here)

Overall it was very easy and quick to migrate !