🠐 All Articles
2021-01-28 • Luc Kusters

Using Vim, Markdown and Pandoc as a Blogging CMS

Why I Don’t Like Using Visual Text Editors

Many people use visual editors to create their blog. Be it a WordPress website or some blogging tool like Medium. Great, I think, if that’s your thing then stick with it. For me, however, this is completely out of the question for one simple reason. Visual text editors drive me crazy.

I wrote a whole blog post about it, you can check it out here. That said, the reasons I don’t like visual text editors anymore is due to the fact that I got used to using Vim. And the problem is: Wordpress or Medium don’t work nicely with Vim. There are some ways to couple them but it’s just messy and I want to keep it simple. Moreover, these methods of keeping your content may be slightly more “convenient”, but they also just feel bloated and over the top for me. Sure, if you need to run a website and don’t have time to mess about with the settings on of your server and need everything to be done quickly, don’t use the method I’m proposing here. But if you’re looking for something that is, relatively speaking, extremely lightweight, then keep reading because it’s actually super simple! ### Why I use Markdown + Pandoc I run my own website using an Nginx server. All I want to do is serve static content. So all I need to do is create static html files. I find writing HTML extremely tedious, so that’s when I started looking for ways to improve my workflow. Now I’d already used Markdown many times to create pdf files quickly using Pandoc. For those of you that don’t know Pandoc: It is a Linux terminal application that let’s you easily convert between different file types. I also knew that Markdown was basically the same as basic HTML without the HTML tags. So I got the idea, why not use Pandoc to convert Markdown into HTML? Easy!

In fact, Pandoc has this amazing feature that let’s you create template HTML files and inject the HTML converted from a markdown file directly into your template. Then all that is left is to upload this static file to your server and there you go: a minimalist CMS without any of the bloat that comes with a regular CMS.

The Vim, Markdown, Pandoc Workflow

I have to admit, this isn’t really a CMS replacement, it’s simply a workflow. But it’s a damn good workflow! If I want to create a new static HTML page for my blog I have a few steps to take:

  1. Write my blog post in Markdown
  2. Convert my markdown file into HTML using Pandoc and a template
  3. Upload it to my server using rsync

The cool thing about this is, if I ever want to change the layout of my website, all I have to do is change the template and then reconvert all the markdown pages! And you don’t even have to do it by hand, I simply wrote a small shell script that does it all for me automatically. Then all that is left is to upload the new pages to the server and voilà.

Pandoc and HTML Templates

To make Pandoc convert the markdown file into the static website I want, all I have to do is invoke the following command:

$ pandoc -i article.md -o output.html --standalone --template=mytemplate.html

You can read the command like this: we have an input file (-i article.md) and an output file (-o output.html). The --standalone option tells Pandoc to create a “stand alone” website, i.e. a website that by default uses a standard HTML template to convert the markdown file into a fully functional HTML page. The --template= option allows us to use a custom template. This template is simply a HTML file with some custom tags which Pandoc recognises to inject the Markdown into. If you intend to use this workflow to create your own website, I advise you to take a look at the standard template. You can take a look at it by running the following command:

$ pandoc -D html > template.html

Change it to your liking or look at one of the many templates that have been created by others online!

Converting all markdown files using a shell script

To make life easy, I wrote a shell script that converts all of my markdown files into HTML files with pandoc and the template. It’s a really simple script and I intend to publish it on my github page soon. It’s probably nothing special, but if you want to skip the step where you have to write your own script you can check it out here.

The Pros and the Cons

It’s not all sunshine and rainbows of course. Using a method like this gives you a lot of freedom over your website but it can also be a little restrictive in other ways. These are the pros and cons I could think of.

Pros:
  • Lightweight
  • Doesn’t require any software to run on your server (all of this can be installed on your PC/Laptop) except for the web server itself.
  • Easy to use if you’re already comfortable with terminal applications
  • Gives you exact control over your website
  • Allows you to use any text editor you want
Cons:
  • Not as “simple” out of the box as a traditional CMS
  • If you’re not used to the workflow, you might be scared off by it
  • More advanced HTML (such as inline videos) aren’t as easily implementable when using pandoc.

If you found this interesting, I’d highly recommend giving this method to create your own website a try!

🠐 All Articles