Adding a Microblog to Jekyll

Since I learned about micro.blog back in January I wanted to give it a try on my blog. For the last few days I had a few attempts on it. And as you can see at xam.io/microblog and on micro.blog I was successful. Now I want to share how I implemented it.

A hat tip to the Creating a Microblog with Jekyll post which covers a lot of the groundwork. I picked up a lot of his ideas and will focus a bit more on the integration with my existing blog in this post.

A Collection for the Microblog

Since I wanted to keep the regular posts separate from the microblog posts, I decided to use a collection to do so. If you don’t care about this separation as much, using a dedicated category within the regular posts is probably the easier option.

So here the configuration for the collection:

collections:
  microblog:
    output: true
    permalink: microblog/:year/:month/:title/

I decided to keep the :year/:month/:title path for the microblog posts, but on level deeper at microblog — of course the permalink schema is totally up to you.

This configuration will pick up any files in the _microblog directory, interpret them as part of the microblog collection and create a rendered HTML page in the output directory.

Adding Microblog Posts to the Index Page

Items from collections aren’t part of the site.posts array that’s normally looped over on the index page, listing one item after the other. Instead they can be accessed by using site.microblog. To merge them together (and have them paginated), I replaced the (no longer maintained) jekyll-paginate with the jekyll-paginate-v2 gem.

In the front-matter of my index.html I now have this configuration to paginate over both, the posts and the microblog:

--------
layout: default
pagination:
  enabled: true
  collection: posts, microblog
  per_page: 10 # Number of entries per page
  permalink: "page/:num/" # Permalink structure
  sort_reverse: true # Newest first
--------

{% for post in paginator.posts %}
    {% if post.collection == 'microblog' %}
        {% include microblog.html %}
    {% else %}
        {% include post.html %}
    {% endif %}
{% endfor %}

The microblog.html is a reduced version of my post.html template that usually renders a blog post.

Creating Separate Pages for Posts and Microblog only

As you can see this blog also has Posts page (containing only regular posts) and a Microblog page containing only the microblog posts.

To do so I have copied the index.html as microblog.html (for the microblog) and as posts.html (for the regular posts). But changed the collection: frontmatter to only include microblog or posts.

The permalink structure of the pagination is relative to the source directory, together with the permalink configuration for posts and microblog, this is the current URL schema on this site:

/ -- Page with microblog and posts
/page/:num/ -- Pagination for both microblog and posts

/posts/ -- Page only with posts
/posts/page/:num/ -- Pagination for regular posts
/:year/:month/:title/ -- URL for single posts

/microblog/ -- Page only with microblog
/microblog/page/:num/ -- Pagination for microblog posts
/microblog/:year/:month/:title/ -- URL for a single microblog

Adding a Feed for the Microblog

For now I keep my regular feed (available at /atom.xml) limited to regular posts only. But I created a separate feed for the microblog (/microblog.xml).

Since also the regular feed doesn’t use any Jekyll plugin, I also opted for the vanilla approach for the microblog feed — my microblog.xml template:

--------
layout: null
--------
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>xam.io | Microblog</title>
    <description>Microblog of Max Kleucker</description>
    <link>{{ site.url }}</link>
    <atom:link href="{{ site.url }}/microblog.xml" rel="self" type="application/rss+xml" />
    {% for post in site.microblog reversed limit:50 %}
      <item>
        <description>{{ post.content | xml_escape }}{% if post.external-url %}{% endif %}</description>
        <pubDate>{{ post.date | date: "%a, %d %b %Y %H:%M:%S %z" }}</pubDate>
        <link>{{ site.url }}{{ post.url }}</link>
        <guid isPermaLink="true">{{ site.url }}{{ post.url }}</guid>
      </item>
    {% endfor %}
  </channel>
</rss>

This feed is the source for my micro.blog account as well.

Creating Microblog Posts

So publishing works, we can manually create a new file in the _microblog/ directory and it will be published on the index-page, the microblog-page and the microblog-feed. Yeah!

Creating a microblog post means to manually create a file at _microblog/<YEAR>-<MONTH>-<DAY>-<TITLE>.md. In particular the <TITLE> part is a bit unfortunate: Per @manton’s definition the a microblog doesn’t use titles for posts. Yet you can’t omit it, since otherwise you could only create one entry per day.

So I wanted to have something quick like the jekyll post "my-title" command. I decided to a add a Makefile that can create a new microblog-file from a template and open it in my editor of choice right away — with an autogenerated title, so I don’t have to care about it.

The template (at templates/_microblog):

--------
layout: microblog
date: %CURRENT_DATE%
title: %POST_TITLE%
--------

And the Makefile:

# Makefile
MICROBLOG_TEMPLATE := _templates/microblog
POST_DATE := $(shell date +%Y-%m-%d)
POST_TIME := $(shell date +%Y-%m-%d\ %T\ %z)
POST_TITLE := $(shell openssl rand 100000 | shasum | cut -c1-8)
POST_FILE := _microblog/$(POST_DATE)-$(POST_TITLE).md
.PHONY: new-microblog
new-microblog:
    @cat $(MICROBLOG_TEMPLATE) | \
    sed "s/%CURRENT_DATE%/$(POST_TIME)/g" | \
    sed "s/%POST_TITLE%/$(POST_TITLE)/g" > ${POST_FILE} && \
    subl ${POST_FILE}

Running make new-microblog on your shell will do the following and leave you with a new microblog post ready to publish:

Read the template from _templates/microblog
Replace the %CURRENT_DATE% in the template with the current date and time
Replace the %POST_TITLE% with a randomized 8-characters string
Save this at _microblog/<CURRENT_DATE>-<RANDOMIZED_TITLE>.md
Open this file in vim. You might change this to the editor of your choice.

Where To Go From Here

Setting everything up, I ended up learning a lot about the Micropub standard and Webmentions. The IndieWeb page is a great resource for this stuff. But in short, there is a whole set of specifications and standards defining the protocols to run your own micropub backend. And Webmentions are a neat way to let somebody when you referenced them.

Yet these protocols need a dynamic webservice to actively work. That might look a bit counterintuitive to running a static blog, but on the indieweb wiki there already are a few ways to do so. But that’s for another weekend.

Blog