Blog Setup¶
Summary¶
I have just started to rewrite my blog using Sphinx and its extension Ablog. As an extra, I have setup a part of the blog as a Zettelkasten – which is more or less a glorified wiki –, and also I have configured Emacs to write posts in Org mode and export them to Restructured Text, which is what Sphinx expects.
Initial setup¶
mkdir blog && cd blog
python -m venv venv && source venv/bin/activate
pip install ablog
ablog start
This will create an initial structure that looks like this:
.
├── _static
├── _templates
├── about.rst
├── conf.py
├── first-post.rst
└── index.rst
The only customization that I have made is to have all posts in a dedicated
subfolder. You need to specify a pattern for the post files in conf.py.
blog_post_pattern = "posts/*.rst"
Now the directory structure can be something like this:
.
├── _static
├── _templates
├── about.rst
├── conf.py
├── index.rst
└── posts
├── blog-setup.org
└── blog-setup.rst
Adding pages that are not posts¶
I also wanted to have a part of this site that does not really need to be structured as a blog, i.e. pages that do not need a date, are not ordered chronologically and are related only via internal links.
The main advantage of using Sphinx for this website is specifically for those pages, so that they get indexed and are searchable.
The ablog start command already created an index.rst file with a section for
“Recent posts”. In order to have more pages, you just need to create a
subfolder, add .rst files there, and list at least one of them in the index page with the doc directive.
Zettelkasten
------------
- :doc:`Start page </zettelkasten/start>`
With a folder structure like this:
.
├── _static
├── _templates
├── about.rst
├── conf.py
├── index.rst
└── zettelkasten
└── start.rst
Adding more zetteln¶
In order to have a Zettelkasten structure, pages inside the folder have to be able to reference each other and the start page. You can get into a recursion error if you list in a toctree directive a page that already references the current page in another toctree directive. Therefore, remember to use the doc directive in order to create links back to the start.
For instance, with a first post that links to a second post, and both of them linking back to the start page, one would have these contents:
└── zettelkasten
├── first-zettel.rst
├── second-zettel.rst
└── start.rst
The start page is:
My own Zettelkasten
===================
Which is just a fancy way of saying "my own wiki".
.. toctree::
first-zettel
The first zettel is:
A first zettel
==============
This page is referenced from the Start page of the Zettelkasten.
.. toctree::
second-zettel
And the second zettel has this contents:
A second zettel
===============
This second zettel references the start. Try not to reference the first one,
or you will get into an error of recursion, since that zettel references this
one.
- :doc:`start`
Writing posts with Org-mode¶
This is probably only relevant if you are an Emacs user.
Since the blog post pattern of ABlog (and in general, Sphinx) only picks up
.rst files, I can write .org files in the same folders and export them to
.rst with ox-rst, a package availble in MELPA.
The header of those files has to be something like this:
#+TITLE: Blog Setup
#+AUTHOR: Luis Osa
#+DATE: Sun Nov 8 22:04:59 2020
#+OPTIONS: toc:nil num:nil
:tags: meta
Notice that the :tags: line is actually raw RST. If you use a #+TAGS header
line in Org, it will not be exported to the .rst file. Also, notice that the
#+DATE is a full timestamp and not an Org datetime; those do not get correctly
picked up by the Sphinx engine.
After exporting the Org document to RST, the :Author:, :Date: and :tags:
lines are underneath the main title. Since ABlog expects to find them as front
matter, you need to manually move them to the first lines of the file. There
seems to be no way to define front matter with ox-rst. I hope this can be
fixed in later releases.