A blog? A blog!

desc

tl;dr just wanted to have a blog; installed Zola; created a theme; wrote a simple program to be able to write blog posts with Joplin

Hello and welcome. This is my very first blog post! Let’s start with an article about my short (technical) journey how I landed here and how I set up this blog.

First of all I would like to point out that I’m not even sure that this blog will survive for a long time. I unsure if I will ever write a lot of post. Maybe it’s just a short phase. Maybe I will write only one post per year. Or maybe this is my first and last post ever. Nobody knows. Only the future will tell…

Well, at least I want to define a goal: What I write should be online as long as possible. I don’t want to maintain a full-blown server-side system like Wordpress or even a CMSs like Joomla the rest of my live. I want something with minimal maintenance, no dependencies and minimal costs. Sure, I could pay for some hosted service or even use some free blogging platforms, but I really like to own my data and have full control over it. And besides, how can I be sure that these platforms will exist for long?

Choosing the right software

There is definitely no lack of choices when it comes to good blogging software. None of the solutions fits all use cases and requirements. So, first thing first:

What are my requirements?

• fast, scalable and reliable
• secure with minimal maintenance
• easy to write new blog posts
• cheap

What I don’t need is dynamic content. I want to just write some wall of text and publish it. I don’t need complex user management with different roles and permissions and… you get it. Maybe, just maybe, in the future, some kind of feedback system like a comment section would be nice. But I’ll leave this problem to my future self. 😉

Therefore, what I really want is some plain old static website. No server-side scripting language. No databases. Just files.

Having a static website doesn’t mean I have to write and customize plain HTML every time I want to publish a new blog post. This would be highly uncomfortable (at least for me, because I am not used to write a lot of HTML nowadays). Using static site generators are a common solution. This means, I can write down a blog post in an arbitrary language/style and then generate all html/css/js files automatically.

There are several different site generators out there. A fairly comprehensive overview can be found at https://www.staticgen.com. There are also some providers who have specialized in hosting such static content and which offer some nice tools to deploy your static site even faster and easier.

Static site generator

I chose Zola as the generator software with no particular reason other than it fits all my given requirements, but this would also be true for (almost) all other static site generators. Zola is written in rust. To be honest, it has really no outstanding features. Therefore, it’s quite minimal without too much overwhelming and useless functionalities. It has one job and it does it well and fast.

Hosting

I have my own server(s) and domains for a variety of reasons. It’s really easy to host a static site yourself. That’s the beauty of having just a bunch of files. You don’t need any special or even powerful hardware. A cheap VPS is all you need.

I’m using nginx with certificates from Let’s Encrypt to host the files myself.

Writing

Up until now I just talked about how to generate the final HTML files and how I want to distribute them. But how do I write a post?

Zola uses markdown as an input. I could use any editor I want! The problem is, that I need to sync or upload the files and that I have to call Zola manually to regenerate the final output. A lot of people are using git for this task and some kind of CI runners to trigger Zola and deploy the files. Don’t get me wrong: I love git like any other developer here. You get versioning, it’s installed on every device I use, it’s familiar. But on the other side, it’s also clunky, not really handy on mobile devices and slow to use – after all, you have to start the synchronization process manually and think about a good commit message.

I want something super simple and easy to use. Something that has a good usability on every platform I work with (Linux, Android and, if it has to be, also Windows). Something where I can outline a full blown blog post or just gather some smaller thought.

In the past, I tried a lot of different note taking apps. Recently, I got stuck with Joplin. I love Joplin. It’s really easy to use, is always available and I can sync my notes across all my devices. Wouldn’t it be nice to also write my blog post with it? In the end both, Zola and Joplin, are using Markdown.

Unfortunately it is not possible to use the output of Joplin directly as an input for Zola. As I already said, both are using Markdown for content, but they are using vastly different solutions to store metadata, such as publishing date or tags. Zola is using a more standardized way. They adopted something called Front-matter in TOML-format (described here). Whereas Joplin is using their very own solution… and they won’t change it (see issue 508 or 1080). I mean, it’s okay, Joplin really isn’t meant to be used as a blog writing platform. Its output is more like a traditional database. Fortunately, the “database” is easy to parse and easy to transform to a Zola-friendly format.

My road to a static blog

1. Setting up Zola

Installing Zola on my server was really easy. I’m using Fedora and just need to do the following:

$ sudo dnf install zola

2. Creating a theme

Zola itself is just a generator. To actually use it, it needs some kind of theme. A theme consists of different templates and various helper functions. There are a bunch of themes already available. I used some of them as a source of inspiration, but I didn’t love any of them. So I created my own, heavily inspired by https://grh.am.

Zola uses tera as its template engine. It’s quite similar to Jinja2, a template engine I used a lot in the past. Therefore, it was quite straight forward to implement the basic design. I wanted to use as little CSS and JavaScript as possible. No JavaScript would be best. I’m trying to keep it that way. Let’s see how long I can do that.

The first version looked something like this:

I tweaked it a little bit and added another logo. I will probably changes some more things in the near future. But here is a screenshot of how this site looks at the moment:

The template itself is really unspectacular, but if you wish to see its source code, then have a look here: https://git.jdsoft.de/jens/zola-theme-jd

3. Convert Joplin’s database

As I already said, I need to convert the database files from Joplin to a format Zola can read. There is no super easy solution. In the end I wrote a small Python helper program to convert the file formats.

There is a python library called python-frontmatter to read, write and manipulate Markdown Front-Matter files. I even found a fork from NGenetzky that supports the custom Joplin format. With this I was able to read in the Joplin files and output the same data with the TOML Front-Matter format.

I had to convert smaller things like the date format and write some functions to find the corresponding tag-names in Joplin’s database, but otherwise it was quite smooth to implement all this.

The code is ugly as hell, since I just wanted to test my idea and build a quick’n’dirty prototype. I never bothered to rewrite any of it. It just works ™.

If you wish (and have the guts), you can find the code here: https://git.jdsoft.de/jens/joplin-to-blog

4. Sync files and automatically update the blog website

I synchronize my Joplin database with my personal Nextcloud instance. That way I have all notes always up-to-date on all my devices and can write wherever I am.

I can also use this to sync the files with my server where Zola is installed. I enhanced my small python script to get notified whenever a file gets changed in Joplin’s directory and automatically call Zola to regenerate this blog. The python script will only use notes created under the Blog-notebook. All my other notes that I manage with Joplin shouldn’t be part of my blog.

I also have a draft notebook. This will trigger a second instance of my converter script and creates an internal testing blog. That way, I can easily evaluate how my blog post will look like.

5. ??? – Profit!

Now I can write blog posts in Joplin wherever I am and saving it will automatically generate the blog website! There is even an internal testing blog for all my drafts.

Future

There are some open point that I will address later (maybe).

The most important thing is spell checking. I’m not a native English speaker. I probably make a ton of smaller spelling errors (in addition to significantly larger grammar errors). Unfortunately joplin has no builtin spell checking solution. There is an open issue, but no real resolution yet. I will probably use joplin’s feature to open notes in an external editor and then use an editor with spell checking. This will at least work on my desktop machine.

Another thing I would like to have is a comment section. Of course, comments are not static. I would need either an external provider or host some server software myself. I’m unsure what I will do here.

Speaking about participation with a wider community, I would also like to publish the content with ActivityPub. There a some helpful tutorials out there how to implement this.

I also wanted to experiment with some decentralised technologies like IPFS or dat://. A static website should be a wonderful use case.