blog/content/about-blog.rst

About this blog
@@@@@@@@@@@@@@@

:slug: about-blog
:date: 2024-01-10 16:47
:tags: meta, infrastructure
:category: technology
:keywords: blog, pelican, self-hosting, git
:lang: en
:translation: false
:status: published

This is my blog and this article describes its setup and other details about my
intentions. The actual `setup <The setup_>`__ is probably the most
interesting tech-wise.

What is this?
=============

My own space on the internet where I can post whatever and link others to it.
It might end up containing rants, guides, ideas, or maybe nothing at all in the
end. Only the future will tell.

The blog might even serve as my personal web page/introduction. Maybe. Maybe not…

The main motivation is to have low-effort way to post random stuff. Which leads
to my requirements for this thing.

Requirements
============

(The requirements are a bit too idealistic, so not all of them were satisfied…)

- low-effort, me-friendly, low-maintenance – I don't want to have to learn too
  many new technologies to use this. This includes the required technologies:
  Python, Markdown/reStructuredText, Jinja2, git, …
- Technical and math content ~~friendly~~ compatible – I expect that to appear
  here.
- Static site – for security, coolness factor and control. Also static on the
  front-end, because I don't like JavaScript and/or running untrusted code on
  my machine (even when in a sandbox). The SSG should likely be aimed at
  creating blogs, not documentation. Also, self-contained, as in not depending
  on third-party sites.
- No moving parts in the infrastructure (or as few as possible) – if it works
  on my machine, it should just get mirrored to the public site with as few
  modifications as possible.
- Transparent – I should be able to understand it, maybe others could also use
  it as a resource or take inspiration. (At one point, this deployment itself
  started being interesting, so if I can share the background as well as the
  final webpage, it would be cool.)
- Followable – I know you internet guys like to ~~stalk~~ follow people :-)
- Aligned with my values: minimalist, simple, extensible/hackable, FLOSS
- If the platform could distinguish translations and do strikethroughs, it would
  be nice, but that is not a hard requirement.

There are several features of conventional blogs that I consider to be a
non-goals or even anti-goals. Mostly it is about interactivity – I don't aim
for having any kind of comments here, or really anything that would require
JavaScript or complex HTML/CSS. And appearance goes past me as well, I instead
try to let the browser decide how to display this page – more on that `below
<Design considerations_>`__.

The workflow I wanted to achieve is something like: Write the content, git it,
build it (locally, no CI/CD), push it, done. Single write, single push, very
simple.

And I managed to achieve something like that, via learning (too much?) about
git.

.. TODO: fix the worktree bug already!

The setup
=========

Naturally for a sysadmin/netadmin, the setup consists of 7 ~~ISO/OSI~~ layers:

1. **Physical layer**: cheap Hetzner VPS. Not physical, but whatever.
2. **Network layer**: Nginx
3. **Persistence layer**: `this git repo
   <https://gitea.ledoian.cz/LEdoian/blog>`__. I will elaborate below why can
   you see this both rendered here and in the source form in Forgejo.
4. **Content layer**: Markdown or reStructuredText files.
5. **Business logic layer**: `Pelican <https://getpelican.com>`__. It's rather
   popular and written in Python, I didn't look further.
6. **Presentation layer**: I hacked my own theme, because I didn't like any in
   the `pelican-themes repo <https://github.com/getpelican/pelican-themes>`__.
   I was a bit inspired by the layout of `eevee's blog
   <https://eev.ee/blog>`__, but I wanted a dark theme. And as you can see, I
   can't do quality frontend, so it ended up horrible… :-D
7. **Stalking layer**: Pelican's built-in RSS and Atom feed generators. Not
   linked from anywhere at the moment, but `the repo will tell you
   <https://gitea.ledoian.cz/LEdoian/blog/src/branch/blog/output/feeds>`__ what
   hides under the ``/feeds/`` path. Or you can utilize the repo (for personal
   use – the content's license is not decided at the moment)…

Most of this is straightforward, the fancy part is my repo. The repo contains
both source and rendered content, so that I can point Nginx right at a checkout
and have Git solve both persistence and deployment without additional moving
parts.

There are two tricks in the configuration of Git repositories: pushing to a
checked out repo is enabled by configuring ``receive.denyCurrentBranch =
updateInstead`` in the target repository (which is just a normal repo, not a
bare one), and then I just told my source repositories [#multiple-src]_ to use
two push targets for the remote (the first line *replaces* the original push
address for some reason)::

    git remote set-url --add --push blog_remote gitea@gitea.ledoian.cz:LEdoian/blog.git
    git remote set-url --add --push blog_remote blog_user@blog.ledoian.cz:blog_dir

The blog user is just a user with SSH access via authorized keys, no special
sauce there. Nginx is then pointed to serve ``~blog_user/blog_dir/output/`` at
``blog.ledoian.cz``. (The |git-remote| manpage requires me to have both
repositories in sync, but as long as I configure all my repositories this way,
I should be safe, and I think I could get away with my blog checkout getting
behind accidentally.)

.. |git-remote| replace:: ``git-remote(1)``
.. _git-remote: https://git-scm.com/docs/git-remote

My workflow and lots of drafts
==============================

It's Git so it's only natural for me to use various branches and repositories
even for a dumb blog. There are in fact 4 stages an article may go through [#skipping-stages]_:

1. A private draft: lives on a branch ``priv/something``, may contain private
   infos (like when I would just copy-paste from terminal without redaction)
   and this branch will probably never be merged to the main repo. Nothing
   about these branches is guaranteed.
2. A public WIP draft: uses a branch called ``pub/something`` which is pushed
   to Forgejo (and in fact also to the blog itself, but that is just an
   implementation detail). The draft is either does not build or is very
   incomplete and I expect to add stuff in a way that could break the build, so
   I put it on a separate branch. The branch will be probably merged to the
   main branch (called ``blog``) when it is ready.

   The ``pub/…`` branches can be created either manually or by cherry-picking
   from the respective ``priv/…`` branch, but that will likely not be
   distinguishable. (I am too lazy to keep the references even in the commit
   logs.)
3. When a draft is almost ready (or the content has simple syntax), it gets
   placed on the ``blog`` branch. The only thing that designates it as a draft
   is ``status: draft`` in the frontmatter, which means that the article will
   get rendered and put somewhere on the public blog, but not reachable from
   the title page ("unlisted").
4. Of course, eventually (and hopefully) the article gets published for
   everyone to see. At that point, it is complete (or at least that is what I
   thought when marking it as published). Possibly it might be updated in the
   future, but no such update is anticipated at the moment of publishing. [#update-this]_

I use Git to synchronize my private branches among machines, so there are
actually two "server-side" repositories (private and public one) and thus two
remotes. [#private-branches-wish]_

As for the actual workflow, for the main branch it usually consists of: writing
content, committing it, building the web, checking it locally, committing the
built blog and pushing it. Sometimes I do the commits together, but I always
separate the rendering/building commits from the content-creating ones, so that
I can handle those differently if needed (i.e. there is no point in
cherry-picking the built content, I can generate it). [#git-purists]_

For other branches I use some applicable subset of the steps above, probably.

Design considerations
=====================

The appearance of the blog is maybe not nice. That is for two reasons: I don't
have the right idea about how to make it much better and I want to have a
rather simple CSS for the web. The latter wish is because I tend to tweak
appearance of sites I visit using my own styles, so I would like you to be able
to do the same.

And for the former reason, if you have any ideas / improvements (including user
styles), hit me at `blog@pokemon.ledoian.cz <mailto:blog@pokemon.ledoian.cz>`__ :-)

My overall idea is a dark-by-default [#light-theme]_ minimalist page with a single menu on the
right containig all the relevant links. The page should not dictate too much
but rather let the user agent decide the rendering (`it does anyway…
<https://html.spec.whatwg.org/multipage/rendering.html#rendering>`__).

I want my blog to render similarly in Gecko-, WebKit- and Blink-based browsers
(e.g. Firefox, Badwolf, Qutebrowser). Others should be usable.
Browser-/engine-specific styles are not welcome – let's keep it simple. And no
JavaScript…

Work in progress / TODOs
========================

This thing is at the moment very barebones, which is sufficient for the main
purpose. However, I would like to have some features here, one day, hopefully:

- Dates in the article headers (and maybe more improvements of the theme, see
  above)
- Stable category and tag names and a page with a description of them. As of
  now I haven't really invented a system of sorting my content, which leads to
  a mess… Please don't rely on categories having any particular name / URL for
  now.
- Link the RSS feeds from somewhere
- Personal info with links to my other profiles
- Some linking to the Fediverse and using it for comments (since there will be
  no comments here)
- Sensible translations, maybe (if I/someone ever get to write the same content
  again in a different language…)
- Improve the list of talks I've given (create some kind of sensible table maybe?)
- Decide on a licence for the content (If you want to utilize something here
  before I do that, please ask me, I think we can find a way :-))

If you are so upset with this blog (or maybe bored) that you want to improve
it, send me patches / ideas. I don't expect anyone to do that, though :-D (And
I do not promise you that I will use the patch, even if it matches all my
opinions above. I also have some gut feelings about what I like…)

Also, tell me if you hate something else about my page. I want to at least know
whom I upset :-D (but I will probably also think about your gripes and whether
I can and should try to avoid them…)

-------

.. [#multiple-src] I also use multiple machines on which I can write stuff.

.. [#skipping-stages] I am lazy and chaotic (good), so the stages are optional
   and non-linear, and sometimes involve paper. This article is a prime
   example: parts of it were on two different private branches, but at the end
   I wrote it from scratch directly on the main branch. And the requirements
   were written on a paper originally.
   
   Nevertheless, the general idea still holds and may inspire others, so it
   makes sense to keep this part in the article. (Also, this footnote might not
   make sense before reading the definition of the stages, but I didn't find a
   better place to put it…)

.. [#update-this] Well, given this article contains some future plans, I
   actually anticipate update of this one, but maybe not in the near future. So
   the outline is not really correct, but I make the rules :-) (There
   were some build breaks on the main branch, too :-D)

.. [#private-branches-wish] I would love if my Forgejo could have "private
   branches", but I understand that the overhead for doing this is not nice,
   since it would need to be able to decide for any object, whether it is
   public or not (you can do ``git fetch <remote> <object-hash>``) and somehow
   keep track even with rebases, merges, force-pushes, many branches, … Having
   a separate private repository is not a big problem in comparison.

.. [#git-purists] Git purists might want to tell me that committing build
   artifacts is not good practice. I know and I explicitly don't care in case
   of this repo, because here I prioritise my own comfort of being able to
   check everything locally and then be reasonably sure the deployed version
   will also work, all this with only a single push somewhere. Of course, one
   could argue that with that there is no reason to create two commits, but it
   does not really bother me to run something like ``git commit -m"render"
   output/`` when I am sure it works, and this keeps readable diffs separate
   from the non-readable ones (i.e. the changes in generated HTML).

.. [#light-theme] Having the page be dark-by-default is my preference, but I
   respect that others may prefer light sites. However, I have not yet
   determined what colors should be used (probably still cyan / blue / maybe
   purple-ish, but I don't know what shade) nor understood how to use
   ``@media(prefers-color-scheme)`` in a maintainable and simple way (in the
   context of my theme). So naturally, this is postponed to the future…