The Design for this Website

2022-05-13

Post Structure

The posts themselves are written in Markdown, and are kept in the /posts folder with the following pattern: YYYY-MM-DD_post-name.md.

I prepend the date when the post was written so it can be easily sorted chronologically by publish date when listing the files from the /posts folder.

Then, it comes the identifier of the post, which are always two-words. If I wrote one post a day for 50 years, this would amount to around 18000 different identifiers, so two English words are more than enough.

Static Generation

I use a couple of Python scripts in the /scripts folder:

index.py generates the home page, according to the Markdown files which are found in the /posts folder.
post.py generates an HTML page for a single post, according to its Markdown contents and the HTML template in templates/default.html.
posts.py lists all the posts and runs post.py for each one.
sitemap.py regenerates the sitemap.xml so search engines can index all the posts.

All the static files intended for public consumption are put in the /www folder.

The Server-side

This site is served with the cheapest possible Debian Linux instance. The web server is nginx and it is configured to look for HTML files be default, meaning that we don't need to append .html needlessly to every post URL.

The post identifier, the two-words, make up the URL of the post. More specifically, the post can be found in the canonical URL https://breder.org/two-words.

Publishing

When I feel like writing something, I fire up vim and start a Markdown file on /posts. Then I run make to generate the HTML page for the post I've just written (through calling the Python scripts).

Finally I run make push to rsync the changed files over to the public directory on the server. That's it.

Version control

Everything is kept in git, including the Markdown files for the posts, the scripts, the webserver configuration and the generated HTML pages.

I could do it without storing the generated HTML pages on git, but I find it useful to run git diff to ensure changes are as intended before i do make push to rsync the changes over to the server.