.. SPDX-FileCopyrightText: 2025 Jani Nikula <jani@nikula.org>
.. SPDX-License-Identifier: CC-BY-NC-ND-4.0

:date: 2025-05-04
:tags: Sphinx

===========
First Post!
===========

This is my blog. There are millions of others, but this one is mine.

Seems like blogging has gone out of fashion, which must mean it's just the right
thing for me to start doing. Right? I could go into great lengths about *why*
I'm starting a blog in 2025, but I doubt anyone cares. (And I'm not sure I have
an *answer*, anyway.) I'll just try to get this first post out of the way, so I
can jump into proper technical topics in future posts.

Yes, technical topics. Software, hardware, programming. That's mostly what I
think I'll be writing about. Perhaps occasionally venturing into social aspects
in technical projects.

And I'll use that as a segue into the technical aspects of this blog.

Before starting, I had a handful of technical requirements:

- Self-hosted. I already have a web server, and a (placeholder) home page. I
  don't want to depend on yet another service provider.

- Static web pages. I want to build locally, push the results to the server, and
  not worry about the security of some humongous blog engine.

- No comment section. I don't want to worry about moderating a comment
  section. (The acute reader observes there's a social aspect here. Or lack
  thereof. I might look into linking posts to my `Mastodon account`_, so
  readers, if any, can follow-up there.)

- Plain text source, specifically `reStructuredText`_, because, for better or
  for worse, that's what I've become used to, and have more experience
  with. Nothing against `Markdown`_, this is merely a personal preference.

.. _Mastodon account: https://floss.social/@jani

.. _reStructuredText: https://docutils.sourceforge.io/rst.html

.. _Markdown: https://en.wikipedia.org/wiki/Markdown

Since I already have `quite`_ a `bit`_ of `experience`_ with `Sphinx`_, it was
quite natural *for me* to look into it also for blogging. Even if, objectively,
it's not really geared toward blogging. But Sphinx being extensible, there are
also extensions for blogging.

I spent all of 15 minutes laborously studying the relative merits of various
alternatives, and settled on Sphinx and the `ABlog`_ extension. This was never
going to be an extensive comparison of blogging software. With ABlog I followed
the same rule of thumb as I do for most new software I try:

.. admonition:: Jani's Rule for New Software

   One must be able to get some concrete results with the software in the first
   five minutes, or it's not worth it.

That may seem impatient, but my point is, if you can't get the most basic
example use case working quickly, you're probably in for a painful experience
long term. If you're a software developer, this is my plea to you: Make it
ridiculously easy to start using your software. Use sane defaults, do
autodiscovery, have good documentation with examples, etc. Lure the impatient
users in with a smooth experience, and they'll have more patience in the long
run.

ABlog passed that bar. It might not be the greatest thing ever, but it's what
I'm using for this blog.

.. _quite: https://lwn.net/Articles/692704/

.. _bit: https://lwn.net/Articles/692705/

.. _experience: https://github.com/jnikula/hawkmoth/

.. _Sphinx: https://www.sphinx-doc.org/

.. _ABlog: https://ablog.readthedocs.io/