Version 1001

In this millennium, I have built around a thousand versions of my personal site. Only 26 years have passed since the millennium started and I have been in the programming game for about 8 years, so that’s practically senior citizen status in tech! These were not just frontend experiments, they were full stack apps and each one reflected the peak of what I knew at the time.

I definitely overdid it. Each version proudly did nothing in production. The bills were just a monthly reminder that I built something I did not even want to maintain and none of it made sense long term. Even with the CMS systems I built myself, I kept hitting limits, mostly in terms of complexity and maintenance. I had no sense of “done” and I also couldn't stop rewriting my code. Since I was always learning new things, everything I built felt outdated right away. So every version had the same ending. I shut it down.

Then I started thinking in a different way. I wanted a site built on text files. Markdown is the format I like most. I tried a lot of apps and even ended up forking a few open-source projects to build my own. In the end, none of it helped. It just turned into more projects I had to maintain. My own tools never worked consistently across Linux, macOS, Windows and Android. Syncing was a disaster. I went too far trying to build my own mini-world where I owned all my data because I did not trust third-party apps after so many data breaches.

I eventually ended up using Obsidian, but as you might have guessed, I could not just use it out of the box. I had to build a custom setup to make writing faster. It is basically a collection of my favorite plugins that lets me run commands to create files from templates and automatically organize them into folders. It worked so well that I will probably write more about it in a future post. I got used to it quickly and now I honestly cannot imagine working without these shortcuts anymore.

One day I sat and thought about something... Obsidian already stores files locally and it felt like those files could just become the website itself. The site would just be a group of Markdown files turned into HTML. I wanted to avoid single-page apps and all that nonsense. I just wanted a clean structure where each Markdown file outputs one page.

I found the right tool almost by accident. At work, we needed documentation for a client in a simple text format. Managers wanted something where they could edit a file and immediately see the result without a full platform behind it. That is how I came across MkDocs. At first, I did not like it because I did not understand how it worked. But I liked the idea behind it. One folder, Markdown files inside and a set of static HTML pages generated from them. The default design was not great and I also could not adapt any of the existing themes because most of them had that typical documentation feel. So I had to build my own theme. It turned out to be surprisingly simple. The theme you see on this site is a custom MkDocs setup with a redesigned header navigation and a mobile-first layout where the content stays centered.

For the documentation I worked on at my job, I had to use web components inside Markdown that fetched data from third-party sources. For this site I did not want to go back into the React world, build a library, define web components and maintain a full build process just to get a simple component. I also did not want static HTML inside my Markdown files. I wanted a system that could detect patterns in the files, parse them and transform them into predefined components based on templates, generating proper HTML blocks during the build step. The goal was to have a custom Markdown syntax that gets converted into something else entirely at build time.

I ended up using markdown-custom-blocks which solved exactly this problem. You define custom blocks, link them to templates and enhance them with CSS and JavaScript. It allowed me to build components like galleries and media cards while keeping everything as plain Markdown. Most importantly, everything is resolved at build time into clean HTML with proper CSS classes, with JavaScript used only for interactivity. There are no runtime transformations and no flickering, unlike some approaches that rely on data attributes and hydration in the browser.

So, what do I end up with? An MkDocs project and a custom theme that includes a set of components I can reuse. To change the site, I just open my editor and edit the files in the “docs” folder.

I also made the theme its own repository and added it as a submodule here, so I can reuse it in other projects if I ever need to. This way, I build components in one place and just import them whenever required.