|
|
|
|
@ -0,0 +1,260 @@
|
|
|
|
|
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…
|
