Blog Setup

Date

2020-11-12

I decided to use Sphinx to create my static website after using it to manage my notes on the desktop. For the most part the website began as a direct clone of my notes style/layout but with the intent of having different content. My reason for a static site is ultimately for longer form content whilst ditching my WordPress site which nolonger seems to meet my needs. Moving away from WordPress means that I would lose the “Blog” format which I have less of an interest in using. That said it would be useful to have a method of indicating changes to the site overtime. ABlog is the compromise.

ABlog adds blog capability to Sphinx to give me the right mix of features. What follows is my setup notes.

Installation

This is simply the case of using pip to install ablog. $ pip install -U ablog

Getting Started

https://ablog.readthedocs.io

I began to read the ablog setup guide and two methods of installation are possible, quick start or adding ablog to an existing project.

Quick Start

I initially began with using the quick start option to create a new test website. The installer was easy to follow and was quickly ready to go. Here is where the differences to my usual Sphinx workflow became apparent.

Instead of running “make html” I now have “ablog build”, a minor change. $ ablog build

The next option I have is “ablog serve” to show the project in the browser via a local webserver. $ ablog serve

This is another minor change but one that I found to have irritating quirks. My previous experience using “make html” build the project and resulted in output that I could run in the browser by opening up the relevant html file. I could then click through to my hearts content. The ABlog build process appears to result in a slightly different output and I found myself seeing an intermediate page between links. Running the webserver resolved this but yet again I had another issue. Navigating through the site following a build I wasn’t seeing the latest version of some pages and found myself needing to refresh the page. This breaks my workflow. I suspect that the final output on a public webserver you wouldn’t notice these issues but for developing locally I wasn’t fully happy. This was the point I almost gave up on ABlog, it was just different enough from Sphinx that I was ready to look for alternatives. Out of interest I decided that I would see what difference adding ABlog to an existing project would make.

Add to Existing Project

Add the following to the projects conf.py.

extentions = [ ‘…’, ‘ ablog’, sphinx.ext.intersphinx’,]

The project is now able to process blog pages in the same way as if I had used quickstart. What it lacks is the integration that the quick start method sets up by default. To begin the integration I first added the following code section to a page to display a list of posts.

.. postlist::
    :list-style: circle
    :sort:

This will show a list of posts processed by ABlog and displayed in chronological order. But once the post is opened the date is nowhere to be seen. The date is specified in the post declaration and would need to be defined a second time to appear in the post. To get around this issue I make use of the “postcard.html” sidebar by adding it into the projects conf.py

html_sidebars = {‘**’:[‘…’, ‘postcard.html’, ‘…’]}

This results in the display of post information in the sidebar which includes the date. The benefit of this is that if the page is not a post then nothing is displayed in its place. This is the behaviour that I want.

The integration is far from complete but back to the issue of how it fits with my workflow. To build the project I am back to using “make html” but this time the html files created I can open manually in the browser without the webserver and without the intermediate page and without needing to regularly refresh. I now have a workflow that is idential to that of my standard Sphinx usage, that gives me blog features without too much fuss. Manually adding ABlog to an existing prokect is my recommendation to anybody who, like me, is not sold on the method that results from using quick start.