Asciidoc
All text sources for this blog are written in Asciidoc. Not only the blog posts, but also the static pages. To use Asciidoc, you have to install and enable the Asciidoc plugin for Pelican. Put this lines into your pelicanconf.py:
... PLUGINS = ['asciidoc_reader'] ... ASCIIDOC_CMD = 'asciidoctor' ...
I use Asciidoctor here, not Asciidoc, the old Python toolchain. Asciidoctor, which is written in Ruby, is the current focus of development for Asciidoc, so it’s best to stick with this. Of course, for the whole thing to work, Asciidoctor has to be installed. It does not come with Pelican or the Asciidoc plugin.
Collect the texts
The articles are spread all over a text repository, where I take notes.[1] A little Python script collects the files from this text repository and puts them into the content folder of my Pelican page. It also collects the images that are included in the text. The Python script uses a YAML file that lists the texts and images which should be copied over to the blog.
Metadata
With Asciidoc, you can (and should) use metadata for your page. I’ll show you the metadata for this blog post as an example:
:category: IT :author: Nik :date: 2025-01-06 :tags: asciidoc, pelican, python, yaml, blog, english :lang: en
They are all self-explanatory. The only thing that’s a little bit tricky is the category. Pelican uses this to list the file under the correct category in the main menu. So, this article will end up in the IT section.
Theme
So far, I use the default theme, Notmyidea. It looks good to me (although the heavy use of black makes it look a bit like an obituary). One day, I will write my own theme. But don’t hold your breath. I thought I have to, so my page would also be properly displayed on mobile devices. But since a while, Notmyidea is even responsive and thus also looks good on mobiles, so the pressure to develop a theme of my own has decreased. Notmyidea will be ok for me for quite some time.