Perl programmer for hire: download my resume (PDF).
John Bokma's Hacking & Hiking

Getting started with tumblelog

In order to get started with a tumbelog site you need a directory for storing the input file, and the generated output. If you have more than one website already you probably already have a sites directory. If not, you probably should create one to organize your site(s). Inside the sites directory, create a directory for your tumblelog. For example, I have a tumblelog at so I have a directory with a subdirectory htdocs.

With the following command:

mkdir -p sites/

all directories in the path are created if they don't exists yet thanks to the -p (--parents) option, see mkdir: making several directories at once.

Next, copy the tumbelog.html HTML5 template file to your site's directory. I named this file plurrrr.html, after the domain of my microblog.

Directory structure for Plurrrr
The directory structure for Plurrrr.

Open the renamed HTML5 template file in your favourite editor and search for SOME SITE. The first hit is the alternative text for your website's logo. I use Plurrrr logo here. The second hit is a link to a site. It currently links to You either want to remove this, or replace it with a link to one of your other sites. In my case I link to my personal site:

Next, replace with a link to your site's logo. I use a 512x512 pixels logo for Plurrrr, which is also used by Twitter in so-called Twitter cards, see below.

I also added a favicon.ico file and an empty robots.txt file. The latter can be created with the following command:

touch htdocs/robots.txt

Finally, use sass to generate a stylesheet and copy it to the htdocs directory. Or have sass write it to the htdocs directory directly. For example:

sass --sourcemap=none -t compressed ~/projects/tumblelog/styles/steel.scss \

The Input File: Markdown Fortune Cookies

The tumblelog program uses a single file as input to generate the micro site. There are two kinds of pages: blog entries and stand-alone pages. The latter can be used to, for example, add an about page and a subscribe page to your blog. Those pages are optional, however. Moreover, it's even possible to create a site without a blog by using stand-alone pages only.

Each page consists of one or more entries, separated by a single % character on a line by itself. Each entry can be written using Markdown. The dialect supported is CommonMark. However, images immediately followed by a line of text are handled in a special way, as explained below.

Separating entries by a percentage character on a line is the same format as used by the Unix fortune cookies file format.

I use the md extension for this file as it is mostly Markdown. Furthermore, I name it after the domain of my microblog, i.e.

Blog Pages

A blog page starts with the date in ISO 8601 format: year-month-day, for example the 13th of October 2019 becomes: 2019-10-13.

You can follow this date by an optional title (recommended). For example:

2019-10-13 An up-to-date manual for tumblelog

The title is not directly visible on the page itself, but used in the title element of the HTML page, for navigation purposes, and in the title of the feed entry for both the RSS and JSON feed.

After the date you can start writing a blog entry. If you write multiple entries on a single day, like me, separate each entry with a % character on a line by itself.

Below follows an example with two entries. This is the way I blog at Plurrrr.

2019-10-13 Lorem Ipsum, and At Volutpat Diam

## Lorem Ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Non sodales neque sodales ut etiam
sit amet nisl purus. Amet consectetur adipiscing elit duis.
## At volutpat diam

At volutpat diam ut venenatis tellus in metus vulputate. Semper feugiat nibh
sed pulvinar. Id consectetur purus ut faucibus pulvinar elementum. Suscipit
tellus mauris a diam maecenas sed.

Each blog entry on a given day is an HTML5 article, and hence can be styled using CSS.

I add new day entries to the top of the Markdown file, with the earliest day entry first, followed by later entries for the same day, if any.

Tumblelog day overview
Tumblelog day view using the Ice style on Plurrrr.

The index page of the blog shows the latest blog entries, the total number of days shown can be defined using the --days argument and defaults to 14 days.

Days are also grouped in week overviews using the ISO 8601 week number. At the bottom of each page an Archive section is shown with links to each week overview.

Stand-alone Pages

A stand-alone page starts with a line using the following syntax:



For example:

@subscribe[subscribe] 2019-10-05 Subscribe

Generates a page subscribe.html with label subscribe, title Subscribe. The date will not be visible on the page itself, unless you follow the date immediately by an exclamation mark, for example:

@subscribe[subscribe] 2019-10-05! Subscribe

The program uses the year of the date to calculate the minimal year for use within the copyright message at the bottom of the page (optional).

I keep stand alone pages to the end of the Markdown file so I can easily jump to them and modify when needed.

Special handling of images followed by text

If an image is immediately followed by a line of text the line of text is considered to be the caption for that image, and semantic HTML is generated for this. For example:

![Alt text](cat.jpg)
Photo of a cat.

is turned into the following HTML:

<img alt="Alt text" src="cat.jpg" />
Photo of a cat.

This makes it possible to style the image and its caption with CSS. The styles that come with tumblelog show several examples of what is possible.

Styling of the figure, img, and figcaption HTML elments
Styling of the figure, img, and figcaption HTML elements using style Happy Cat.

Template variables

The Markdown written in the input file is converted to HTML and injected into a HTML template. Several arguments that can be passed on the command line are available to this template. The complete list of template variables is as follows:

A template variable must be enclosed between a [% and a %], for example:

Copyright [% year-range %] [% author %]

The maximum of the year range is calculated from the current time the tumblelog program is run. The minimum is determined as follows: if given on the command line its value is used, otherwise the minimum year of the date used in blog pages and stand alone pages is used. If the maximum and minimum are equal, just a single year is used.

Twitter Card and Facebook Sharing support

The HTML template file that comes with tumblelog has support for Twitter Card and Facebook Sharing. Just create a large logo, for example I use 512x512 pixels, and add it to the htdocs directory.

Twitter cards for Plurrrrr on Twitter
Twitter cards for Plurrrr on Twitter.

For more information, please read Adding Twitter Card and Facebook Sharing Support to Tumblelog.


I am still working on tumblelog so (small) updates happen now and then. You can check for updates using the git pull command inside the tumblelog directory:

cd tumblelog
git pull

The file has information on what has changed and if you have to modify anything.

If, for example, the template file that comes with tumblelog, tumblelog.html is changed you can use the diff program to compare this file with your template file and modify your template file accordingly. If you don't like the output of diff on the command line but prefer a GUI solution I can highly recommend the program meld:

sudo apt install -y meld

You can use it to compare files or entire directories, and you can still start it from the command line:

meld tumblelog.html ../sites/

Updates are announced on my microblog Plurrrr and my Twitter stream.