Migrating to Jekyll
January 25, 2022• [projects] #jekyll #ssgI migrated this site, on a whim, to Jekyll and now it is deployed via Netlify, with the data on github. I am glad I did it, though it has taken longer than I expected to move the few posts I had on my old Squarespace site. Since I have spent all this time, I should rationalize my decision: I don't have to pay Squarespace $150 a year any more for hardly using their services. Squarespace's analytics product is nice, but not nice enough to keep me there, considering no one visits this site outside the family and the bots anyway. Besides, there appear to be some free alternatives that I could always use1.
A good thing about the process I now have is I don't have to keep making copies of my posts - which have always been written in markdown - before publishing it. I own my content, and it be versioned and tracked. Plus the whole migration was fun (and inadvertent - I only wanted to check Jekyll out, but it was so easy to get the initial site up on github pages that I went the whole way). And just as important, I finally have working footnotes2.
I am listing some of the resources I used in order to get this site up and running in case I ever have to do this again (and if you need yet another migrating-to-jekyll reference post #9991212).
Intial Setup
- Setting up jekyll on macOS.
- Hit issues with using the ruby that ships with macOS. I ended up using rbenv.
- Using a custom domain on github pages.
- Configuring external dns on netlify. Very easy to do. I have to say Netlify docs are excellent!
- Started with Github Pages, later moved to Netlify because I want to keep my repo private. If Netlify axes their very generous free tier, there are other alternatives: Cloudfare Pages, Surge, Render.
Tags, Categories, Permalinks, Redirects
- Started using categories on my posts the way I would use tags, without realizing that the links generated would have these categories in the path. I swtiched later to using an explicit
tags
concept in the Front Matter, and using an explicit permalink field. - In order to generate these tags and have them display on my post, I found these two resources very helpful:
- Jason Miller
- Long Qian
-
Add an archive.html to _includes: {% raw %}
Archive {% capture temptags %} {% for tag in site.tags %} {{ tag[1].size | plus: 1000 }}#{{ tag[0] }}#{{ tag[1].size }} {% endfor %} {% endcapture %} {% assign sortedtemptags = temptags | split:' ' | sort | reverse %} {%- for temptag in sortedtemptags -%} {% assign tagitems = temptag | split: '#' %} {% capture tagname %}{{ tagitems[1] }}{% endcapture %} {{ tagname }} {%- endfor -%}
{% endraw %}
-
Add a tagpage.html to _includes: {% raw %}
--- layout: default --- Tag: {{ page.tag }} {% for post in site.tags[page.tag] %} {{ post.title }} ({{ post.date | date_to_string }}) {{ post.description }} {% endfor %} {% include archive.html %}
{% endraw %}
-
Then one needs to run a script that will generate the tag markdown file for each of the tags one has.
-
- I later learnt about the gem jekyll-archives that does the same thing sketched out by the above two, and a few other things. Probably easier to get it working this way. When I find myself with more time to kill I will probably move to the gem.
- Customizing permalinks.
- In _config.yaml, you can use placeholders from front matter like this:
permalink: /:categories/:year/:month/:day/:title:output_ext
- In _config.yaml, you can use placeholders from front matter like this:
- For redirects, this is as good a resource as any.
Styling
- Adding css attributes to kramdown.
-
Creating callout blocks, like I have at the bottom of this page.
-
Styling blockquotes.
-
To add the custom css, I copied over the main.scss from minima to the /assets directory and edited the file.
-
My blockquote, for example:
{ :; :; :; :; { :; } }
-
I will probably set custom attributes for post fonts and title, using a template similar to the blockquote.
-
- Adding favicon.
- To add pagination, I found this most helpful. Unfortunately, jekyll-paginate is not under active development, and the last release was in 2014. I expect this to break sometime, and I need to find something better to replace it.
- I used this very good guide for adding next and previous post links at the bottom of each post. Had to get rid of index.markdown that I started with and use a index.html instead.
Misc.
-
To add markdown files to the root directory, and not have them show up in the header, make use of
header_pages
in _config.yaml:header_pages: - links.markdown - about.markdown
-
Add table of contents. Need to get this in someday.
FOOTNOTES
I tried google analytics and I didn't like it. It's also the best known tracker, which means many users can block it - like I do. Plus we know it's not really free. There are paid alternatives like Fathom, but at $14/month, too expensive for a tiny site like this. All I want to know is which posts are popular with some accuracy. There are self-hosted analytics like Ackee and Plausible that I will have to try one of these days. Cloudfare Pages comes with analytics support in the free tier. So there are options.
Yay!