new blog, new stack

Well, I want to write more, but can never think what to write about. So here we go, with the most cliché post a developer can do on their new blog: Describing the tech stack behind it.
This blog you see here now, is my first real attempt at a fully self-developed and self-made blog and website.
Before that I briefly used Quartz to generate a site from my Obsidian vault and push it to my Uberspace web host, which works well and is well-suited to make a simple Digital Garden of any Obsidian vault. Quartz provides a few useful features, like easy conversion of Markdown files into HTML pages, rendering a good default theme, with navigation and components like a page graph etc. The source is also open and easy to adjust, just a little trickier to update, if they have been custom changes.
There are also plenty other similar plugins and such out there, which provide very similar functionality, converting and rendering Obsidian notes with a fixed design or theme, like Obsidian Digital Garden or Friday.
This is all fine and dandy, but my “pride” as a web developer myself, I wanted even more control over how my content is being displayed. Also Quartz does not support classic blog feeds and such.
Therefore from the beginning I had in my mind to use a more custom-made solution at some point and kept researching frameworks, plugins and what others did. And it’s hard to believe how many are already out there!
All of them use slightly different approaches, either plugins to be run from inside Obsidian, CLI tools to be executed either manually or by a pipeline. Due to my setup of my vault in Obsidian, where I am mixing private notes with the public posts I want to write, I had a few requirements for the setup:

• convert Obsidian-style Markdown, especially Wikilinks [[like this]]
• be able to link to other notes and include attachments like images
• filtering out notes based on a key, e.g. publish
• in the beginning I also wanted to keep everything in one repository and not expose the source files publicly, as well as not have source code inside my Obsidian vault

Especially that last one was trickier than expected. Many other solutions either force you to keep your Markdown files together with the source code of the website, and often have the entire vault public. For example, even with Quartz, I had to keep two repositories, one for my private vault as I had before. And another to keep the Quartz source code. Meaning I had to either copying over the Markdown files from one repository to another or use Git submodules. The submodule proved the more reliable way, as I could include it in the public repository on GitHub and give the repository access via a deploy key, as still can be seen here. This worked fine, but meant I had to manually update the submodule inside the public repository, whenever there was new content in the private one, and I never got around to automating that process.
After that I also have to deploy the build files somewhere, for which it makes most sense to use my existing and trusted webspace provider Uberspace. Using scp and some deploy keys in a GitHub workflow worked like a charm for that.

This is how the page looked after the above process:

Certainly not bad for a basic setup and being able to publish Obsidian notes relatively easily.
I did keep this for a while, but always with the desire to only use it as a base and at some point replace it.

Even if that time never really came, I kept some notes on other options I stumbled upon in the meantime. One of those that made the next step possible, was the Obsidian plugin Enveloppe. Instead of pushing from one repository to another, this plugin directly talks to the public repository directly from within Obsidian, via the GitHub API.
Initially I wanted to avoid this approach to not have to rely on another plugin and instead just combine this publishing flow with my backup flow to my private GitHub repository. But after trying it out once, I realised it takes away a lot of the hassle, that I would have to do myself otherwise with a custom solution:

• converting Wikilinks into standard Markdown links and map them to the corresponding files: [[link]] -> [](link) (which was more complexities than I thought at first, e.g. what to do with identically named notes in different folders?)
• filters files and attachments based on a property
• map file paths to a designated folder structure
• … and other things I probably couldn’t even think of yet

So with all of this (and more) taken care of by the Envelope plugin, I could get back to the more fun part of making a website (at least to me): Working on the actual page and design!
I just set up Envelope plugin to push to my secondary public repository (after testing with another temporary repository) and started working on rendering these Markdown files with a framework of my choice.
For that kind of choice there are just as many options out there. I won’t go over those here in detail, basically any frontend framework would do the job. I chose Astro for my purpose here, as it’s suited well for static content like blogs and supports many modern web features and technologies.
Setting up Astro for this project was as easy as following their basic quick-start guide and setting up Envelope to push the converted Markdown files to the correct source folder for Astro to find the files. One trickier thing was to find the right format for internal links, to articles and attachments. The settings for Envelope allow a lot of different configurations there, which I had to align with what Astro would expect to parse internally. This was a bit trickier at first and I had to write some short helper functions to help parse the links, especially to retrieve image banners to render for each post.
With that done, working on the actual design and CSS for the site was the easy part and I soon had the below design for the home page:

For more details about that, I recommend just checking the source code and history on GitHub. I will surely work on it more, try to find my own style and design etc. For now I want to keep it simple, but have plans for more proper “blog features” and such.

After that I published the site on my Uberspace web host just like before.
After some testing and tweaking with Google Lighthouse, I managed to get a 100 score:

I suppose it’s okay to be just a little proud of that. Let’s see how long it lasts! ;)
In the meantime, feel free to contact me with suggestions and such.