Setting up Ablog

Background

This has been difficult for me. I went down a number of alleys which did not lead to joy. In the end, I decided on a very generic presentation so that ablog works.

I decided on the generic approach for two reasons:

  1. I got it working. I didn’t want anything to break which led me initially to despair and to work late.

  2. My blog posts are more or less temporary. They may stay in the blog repository, but I will be moving most of them to another repository where they will be stored in writing collections. This means they don’t have to stay searchable and I don’t expect my readers to have to search through pages of archives to find them. The most likely person to search is me.

Let’s Get Started

ablog is written in python so you will need to have pip installed. I am using a Debian installation so I had to install it manually. I already had Jupyter Book installed. This means I already had Sphinx and the myst-parser installed. With jb installed, I was running Spinx 3.5.4 running, but was able subsequently to update both Spinx and myst-parser to later versions. I think this helped me but I can’t say for sure. Your mileage may vary.

My install command is simple:

sudo pip3 install ablog

Starting Ablog

I created a new repository on github which I cloned so basically I had a blank repository. Then I was able to set up the initial framework for ablog. This is important because ablog cannot be installed in a directory with an existing conf.py file. ablog start

You will be prompted for several bits of information including where to install ablog. The directory must exist. The other pieces of information will be written into your conf.py file.

Restructured Text or Markdown?

The first decision you need to make is whether you want to write your posts in Restructured Text (rst) (the language of Sphinx) or use Markedly Structured Text (myst). Myst uses .md for files while Restructured Text uses .rst. You will notice that ablog uses .rst. Fortunately, once you have Myst set up, you can use both.

If you already know markdown, you can get along fine with Myst. I became familiar with Myst through jb and its a handy reference with its [Myst cheat sheet.

Get Myst Working

You need to add myst_parser to the extensions variable in conf.py. Remember, this is python so follow the format of the other extensions.

extensions = [
    ...
    "myst_parser",
    ...
]

Tip

Be sure to notice the square brackets [].

You also need to add this statement. I put mine at the end of the conf.py file:

myst_update_mathjax = False

I also put this to enable additional features of myst.

myst_enable_extensions = [
    "amsmath",
    "colon_fence",
    "deflist",
    "dollarmath",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "substitution",
    "tasklist",
]

My previous tip about square brackets [] applies here, too.

Front Matter

Finally, each post needs front matter. I am using the yml format.

---
blogpost: true
date: August 15, 2021
category: Tech
---

Note particularly the three hyphens `-` on a separate line to
start and end the front matter. There are several other possible
pieces of information, but these are the most critical.

The `index.rst file

I almost left the index.rst file alone. In my various iterations of dealing with ablog this gave me the most trouble. That’s why my blog page looks so generic and boring. It just works.

  • I took out the references to about me because I reference that info elsewhere.

  • I also deleted the file in the directory and the index.rst file.

Building the Blog

To build the blog you simply type:

ablog build

You will get a warning about mathjax. Review other warnings as needed. Your new web site is in the _website directory.

Cleaning

I find it useful to delete the _website directory before a build. ablog has a command for this:

ablog clean

Getting Online

I use ghp-import to get my pages published. It’s another python program I learned about from jb. ablog has its own deploy function but I haven’t checked that out yet. ghp-import only handles gh-pages so I have to commit my own source files to github which is just fine with me for right now.

Conclusion

I was using nikola to publish my blog. It’s fine, but it’s heavier to use. There’s a lot of flexibility and the option of building pages, too. I just want a simple blog program and so far, ablog satisfies this requirement. I need to learn more about the .. toctree directive in Sphinx to clean up my landing page and add some more interesting elements to it.

Previous: Insecurity   Next: Entry Points