Migrating to Jekyll

I 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 use¹.

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 footnotes².

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 %}

      <h2>Archive</h2>
      {% 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 %}
      <p>
      {%- for temptag in sortedtemptags -%}
        {% assign tagitems = temptag | split: '#' %}
        {% capture tagname %}{{ tagitems[1] }}{% endcapture %}
        <span style="white-space:nowrap"><a href="/tag/{{ tagname }}"><code class="highligher-rouge">{{ tagname }}</code></a></span>
      {%- endfor -%}
      </p>
      

      {% endraw %}

    • Add a tagpage.html to _includes: {% raw %}

      ---
      layout: default
      ---
      <div class="post">
      <h1>Tag: {{ page.tag }}</h1>
      <ul>
      {% for post in site.tags[page.tag] %}
        <li><a href="{{ post.url }}">{{ post.title }}</a> ({{ post.date | date_to_string }})<br>
          {{ post.description }}
        </li>
      {% endfor %}
      </ul>
      {% include archive.html %}
      </div>
      <hr>
      

      {% 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
    

• 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:

    blockquote {
        color: #20151fe8;
        border-left: 4px solid $grey-color-light;
        padding-left: $spacing-unit / 2;
        font-style: normal;
    
        > :last-child {
        margin-bottom: 0;
        }
    }
    

  • 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

Back to top