Introducing Smallblog

For a long time, I wanted to create a blog to share my passion for homelabbing and the fun side projects I work on. My goal was to document my experiences and help others learn from them.

The issue was, I never found a blog engine that I wanted to use. I tried many things: Ghost, Hugo, Jekyll or creating my own in Astro. I loved some aspects of them but always have issues nonetheless. By testing them, I've defined what I want and what I don't for a blog engine:

• Writing posts in Markdown is a prerequisite, as I already use it for READMEs and note-taking
• I want a straightforward process for writing, uploading, and correcting articles. I'm passionate about tech, not about the mechanics of writing, so simplicity is key.
• A customizable experience is very important to me, I love to compose my tools to do exactly what I want and how I want (I used an addon-heavy VS Code, and now I have neovim and tmux fully customized from scratch for example)
• I want to host myself the blog with minimum resource usage (I have a cheap VPS)
• If I build the blog myself I want an easy stack (I'm not an expert JS developer and I hate messing with most of JS ecosystem that I find too complex)
• The blog should work without JS enabled, I know some privacy focused folks deactivate JS to protect their privacy, I don't know the proportion of them, but I want them to navigate the blog comfortably
• I don't want a complex UI
• I prefer a minimal feature set—no user accounts, comments, or unnecessary complexities.

The inspiration

I was stuck at that point for a long time when a friend of mine pomdtr show me his new project: Smallweb. At first, I thought this project was not for me, despite the design of it was quite intriguing. As I was still curious, he helped me deployed an instance on my homelab. I asked him examples to get my hands dirty, and one of them made me realize how I should make the blog worked.

One of the use-case demonstrated was a simple to-do list. Nothing special you'd think, but there's a twist! The app was dynamically rendering from a markdown file, and it had a keybinding for him to quickly edit the markdown file inside another service hosted thanks to Smallweb. I thought "this is like that I want to edit blog posts, this is so easy!". So, I've spent a month crafting a blog engine on this principle, trying to get the workflow of redacting a post as seamless as possible.

After many trials and errors, I have it finally working well enough that anyone can use it, and I call it "Smallblog".

What is Smallblog?

Smallblog is what I called a "lazy blog engine" or a "lazy site generator". It produces sites similar to a Static Site Generator (SSG) like Jekyll or Hugo site, but it's much simpler, because you don't have any compilation step.

Once your site is deployed (which is only made with 2 lines of code using Smallweb), you just write your Markdown files in the right folder, move your images next to them and your post is immediately online!

This allows you to focus on the content, the deployment is easy, and it is a one-time thing only. My favorite aspect of it is the correction. I can correct an online article in seconds if I see a typo.

The following features are also available:

• Metadata handling by YAML formatted frontmatter (a section before your text delimited by ---) in your Markdown posts
• Hidden posts only via the direct URL, to see the preview (not indexed in the first page)
• Custom pages linked through the navbar (as the GitHub link in this site)

To know more about these features, you should check this page in the demo or check the README on GitHub

How Smallblog works?

If you are a dev, you are probably wondering "but how it works?". Well, this is quite simple, there are 2 main kinds of pages: the index and the other pages (mainly the posts).

First, let's focus on the non-index pages, because they are simpler. When a user request a post page, let's say /posts/my-first-post, Smallblog will:

• Look for a file called my-first-post.md in the posts folder
• If the file is found, it will render the Markdown content of the file and put it in an HTML template (+ extract metadata in the frontmatter and include it into the same template)
• If the file is not found, it will render a 404 error page
• Send back the resulted page to the user

Now, let's focus on the index page. Some of you have probably understood what it does at this point, but I'll explain it to not lose anyone. When a user request the index page, Smallblog will:

• Look at the posts folder
• For each Markdown file found, it will extract metadata in the frontmatter and generate a preview
• Generate an HTML page from the list of posts
• Send back the resulted page to the user

So, that's it! You have understood how Smallblog works, this is not so complicated!

Performance

You might wonder how Smallblog performs. That was my main concern when I was creating Smallblog. While it’s not as fast as static sites, its simplicity ensures excellent responsiveness.

I use lighthouse to perform tests on Smallblog. It's an open-source audit tool developed by Chrome which is shipped in every chrome-based browser. The performance score varies from 97 to 99 (using Smallweb). It proves the engine is fast enough, it is probably faster than most websites you are used to.

I will make a post entirely dedicated to the performance of Smallblog in the future, so I will not go into many details here. The only thing you should know is that Marked, the markdown rendering library that I use is amazingly fast.

SEO and Accessibility

SEO and accessibility are essential for any blog, ensuring content reaches a wider audience and remains user-friendly for everyone.

As I'm not a professional front end developer, I had to learn a lot to make the engine as good as possible. I finally developed around lots of best practices like:

• semantic HTML
• metadata tags
• high contrast for readability
• responsive design

With all of this, I made Smallblog really optimized (at least I think) and lighthouse seems to agree with me:

Conclusion

I'm quite proud of what I've done with Smallblog and I love this lazy aspect of it. I will probably reuse this kind of architecture in later projects, 'cause it made the development, as well as the usage of the blog really easy!

If you want to know more, you should check the project on GitHub or in the JSR repo.

Feel free to share this with others who might enjoy projects like this.