.. post:: 2023-07-28
    :category: Blog
    :tags: Tinkerer, ABlog

R.I.P. Tinkerer, welcome ABlog
==============================

`Tinkerer <https://vladris.com/tinkerer/>`_ is dead, or in the words of its
author: retired in favor of `Baku <https://github.com/vladris/baku>`_.

*Baku* is much simpler, uses `Markdown
<https://en.wikipedia.org/wiki/Markdown>`_ and is not based on `Sphinx
<https://www.sphinx-doc.org/>`_.  But *Sphinx* was the reason I chose *Tinkerer*
in the first place, so I looked for alternatives and found `ABlog
<https://ablog.readthedocs.io/>`_.

*ABlog* imposes less restrictions on the directory layout of the source files.
Which is a good thing because it means the directory structure of the old blog
could just be copied and the URLs of the old blog posts stay the same.

*Tinkerer* uses some custom `reStructuredText
<https://docutils.sourceforge.io/rst.html>`_ directives to markup blog posts,
while *ABlog* basically uses just one directive with arguments.  A little script
to replace the directives from *Tinkerer* with *ABlog*\s ``.. post::`` directive
was quickly written.

*Tinkerer* markup with directives:

.. code-block:: rst

    .. author:: default
    .. tags:: a tag, and another tag
    .. categories:: Example, Post
    .. comments::
    
    .. more::    

Translated by the script to the *ABlog* post directive:

.. code-block:: rst

    .. post:: 2023-07-28
        :author: default
        :tags: a tag, and another tag
        :category: Example, Post
        :comments:
        :excerpt: 1

The post date is generated from the directory structure of *Tinkerer* which is
``<year>/<month>/<day>/``, so this information is somewhat redundant.  But  this
is neccesary as *ABlog* allows any directory structure for the blog post
sources.

The ``.. more::`` directive becomes the ``:excerpt:`` argument and this needs
some manual tweaking after conversion.  Unfortunenately *ABlog* doesn't use the
content of the rendered blog post as is to generate an excerpt for the various
listings but extracts the first *n* paragraphs of *text* from the post.  So any
special markup like admonitions, code listings, or raw html get lost in post
listings.

For instance the canvas element in :ref:`chasing_a_dot_on_a_html5_canvas` can
not be seen in a post listing.  Which is the only major drawback I've found so
far in *ABlog*.

I've ported the `hidemail` extension from *Tinkerer* for the ``:email:`` role to
obfuscate e-mail addresses.  Damn those spammers…

For now the blog uses the default `Alabaster
<https://alabaster.readthedocs.io/>`_ theme.  Maybe I keep that, or maybe I try
to write my own theme that resembles the *modern5* theme of *Tinkerer* later.