Categories, Tags, and Series

As we were writing in many different fields, we most definitely needed a good way to be able to categorize the blog posts. That’s why we added in the category and tag entities to our blog to help the users explore and find the articles they want.

We were also writing tutorials or closely related essays about a single topic where simple chronological order was not enough. We needed a way to collect and sort a set of articles that might even be from different categories together with the order we want and we thought the series concept on DigitalOcean was the correct way to handle this use case. Many templates did not have this feature, that’s why we had to either add support to an existing project or create our own blog from scratch.

Bilingual and bidirectional blog templates are rare

We were writing in many different languages. Some posts might get translated into some other available languages later after the original publish, so we made an easy way for writing bilingual posts where each language is a Markdown located in the same directory. This made it easier to see what is available and what is not. It is a simple idea but other templates and frameworks (like Docusaurus) put contents of different languages in different directories entirely, which made things harder for our team.

Now bilingual blogs exist, but not many of them handle a right-to-left language like Persian gracefully. We reviewed many great templates that were written with Astro, Next.js, SvelteKit, and other frameworks but unfortunately many of them had not considered RTL users.

Public repository, contributions, and hosting

We wanted our content to be publicly available in a repository to encourage the community members to either write up their own ideas and file a pull request or fix the issues of previous articles. We also wanted the hosting to be done on GitHub Pages as it was easy, accessible, and free. We also thought other developers might clone our project and use it as their own personal blog so we wanted everything to be easy and without any costs.

These 2 reasons together made us move away from WordPress themes and architectures that require a backend for the blog. This forced us to take the static approach.

Why Not Hugo or MkDocs

Hugo (Go) and MkDocs (Python) were written in other languages and ecosystems. I didn’t research them extensively but I was sure that I didn’t want to bring another language and ecosystem to Basliq Lab’s frontend stack so I ruled them out.

Why not Next.js or Nuxt

These two frameworks are awesome! Having worked with Next.js in many professional projects, I really knew the ins and outs of the framework but I didn’t want to choose the same tool over and over again.

The Astro attempt

At the time that I was starting to work on the Qwill template, I was hearing some new names like Astro and Svelte and I wanted to test them out. The blog was not a critical project and these two relatively new frameworks were already mature enough to be considered as a safe experimental choice.

Astro was my first choice to build the Qwill template. After building a simple mini blog and assessing the experiment, I figured out that Astro is a convention-heavy framework. Though these conventions can be configured and they wouldn’t necessarily prevent me from building the blog, but I didn’t quite like the developer experience. So I deleted the project.

Settling on SvelteKit

I moved on to the second option, SvelteKit. Going through Svelte’s interactive tutorial, I had the first impression that I have found something new. The component model was pleasant. The markup syntax was sweet. And it had its own framework called Sveltekit. Did it support SSG? Yes. Did it support flexible “your project, your thing” kind of workflow? Yes. Did it support Markdown and custom components? Well yes, but actually no.

That was a trick question. These kinds of features don’t normally get baked into general purpose frameworks themselves. I searched and I found a library called mdsvex and it seemed fine. So I reinitialized the Qwill project with SvelteKit, and later I modified the same codebase for the Attempts template.

Converting an MD file to displayable HTML

The first step is to somehow convert our MD file to an HTML representation of it and since we are making the blog with Svelte, we somehow need to integrate it with the component model of Svelte.

We could do this manually by reading the contents of the Markdown file from the filesystem, trying to extract out its metadata and content into the format we need but this sounds way too much work and we are not getting paid enough to deal with that complexity so we use libraries.

We can use a library called mdsvex, that gets added to the Vite bundler as a plugin and defines some logic for the imports of .md extensions. We can install it with:

                        

                        

                        
                        terminal
                
$npm i -D mdsvex
copy
If you are interested in how we can import non-standard files like .md into our code then take a look at this blog post (as opposed to being able to import only .js files).
 
/
 
Engineering Notes
 
 
May 9, 2026
 
Importing the Impossible: How Vite Imports Markdown, PNG, and WASM files
 
Let's see how we can import a .whatever file extension in our JavaScript code.
 
 
Ata!
 
@atareversei
 
 
#
 
software
#
 
frontend
#
 
vite
#
 
bundler
After the installation, we plug it right in to the build system.

                        
                        svelte.config.js
                
1
2
3
4
5
6
7
8
9
10
11
12
13const mdsvexOptions = {
  extensions: ['.md'] 
}

const config = {
  preprocess: [vitePreprocess(), mdsvex(mdsvexOptions)],
  extensions: ['.svelte', '.md'], 
  kit: {
    adapter: adapter({
      fallback: '404.html'
    })
  }
}
copy
Now you can import .md files into your JavaScript code which gets resolved to an object that gives you access to that Markdown file’s metadata (a.k.a. frontmatter) and a Svelte component that contains the Markdown content as HTML.
You can’t send a Svelte component over the network, because it cannot be serialized into JSON, therefore you have to use SvelteKit loaders (you can learn more about them in the tutorial that I mentioned earlier).

Setting up API endpoints and routes for success (and SSG)

For SSG builds you have to define your routes as such that every page can be found and rendered at the build time (yarn run build). The only part that confused me a bit was the list and its pagination.

Often in client-side rendered applications we would set up the client routes for lists using query parameters like /blog/posts/list?page=1. However, for SSG websites we cannot use that format (we can, but the headache is not worth it). We must use routes that can be predetermined beforehand, because the SSG crawler will follow all the links in our applications to discover all the available pages and start rendering the HTMLs.

In this application I found this setup more useful:

CodeViewer

categories

categories/_components

categories/_components/categories-list-view

categories/_components/categories-list-view/CategoriesListView.svelte

categories/list

categories/list/[page]

categories/list/[page]/+page.server.ts

categories/list/[page]/+page.svelte

categories/+page.server.ts

categories/+page.svelte

Select a file to view its content

Bilingual and bidirectional implementation

Things like logical CSS properties and component mirroring needed attention since day one. I have written a separate deep dive about RTL applications here:

/

Engineering Notes

May 9, 2026

Two Directions, One Codebase, Zero Headaches, -1 Z-Index

How to support English and Persian with one line of code?

Ata!

@atareversei

#

css

#

i18n

#

ui

#

software

#

frontend

#

webapp

Styles and multiple themes

I changed the colors and the overall theme of the previous template to create the new one in a matter of minutes. It supports light and dark mode and currently it has one theme though it can easily be extended to support multiple themes. If you want to learn more about the art of styling modern web applications then I strongly recommend you to read this post:

/

Engineering Notes

May 9, 2026

The Proper Way to Style a Web App (I Think)

I've been a fullstack CSS engineer since 2020 and this is what I think.

Ata!

@atareversei

#

css

#

ui

#

software

#

frontend

#

webapp

Bonus: Extending Markdown with components

Standard Markdown features like headings, lists, tables, and links lets you write simple articles with no extra overhead. But sometimes you just want to be able to get out of that restriction. Maybe you want on specific image to have a certain width and be centered. Maybe you want to display an editor like view with many tabs. Or it is just that you want to display a Twitter message with more class and fanciness instead of using block quotes.

Well, you can write plain HTML tags inside the Markdown and most parsers will not escape the tags and copy them directly to the final HTML output. This way you can theoretically display anything you want, but for repetitive usage and complex use cases that gets out of control very quickly. The solution is to use the million-dollar-idea of the new frontend frameworks which is

mdsvex supports importing Svelte components inside the Markdown file. This helps us with encapsulating complex pieces of logic and UI in Svelte components and just use them in the .md files. In this article you can view some of the custom components that I have used, like:

• special words
• code viewer
• post references

If you are not a fan of adding framework-specific dependencies to your Markdown files, then you can extend the syntax of the standard Markdown by using remark plugins or writing them yourself if you are feeling brave. Highlight marks are an example of Markdown syntax extension (they work with double = tokens). Though I don’t recommend this approach too much, because the end result becomes some sloppy JS code.

The happy path of Svelte

Svelte is trying to solve a problem that at least 10 other frontend frameworks are trying to solve it as well. But there are some things that Svelte does it better, and I really like them.

The not-so-happy path of Svelte

The problem is not with the Svelte itself but rather with the tooling around it I think. You expect a flawless developer experience from a world class project like Svelte and then you get stuck at places where you didn’t even expect.

What I probably over‑engineered

I think to create a good-looking blog UI, I spent so much time on small features that they made the whole process longer. Adding these features also caused some errors to surface that I mentioned some of them in The not-so-happy path of Svelte.

Features like code blocks with file names and language logos and components like code viewer forced me to add lots of relatively complex, not performant, and fragile code like manipulating the string representation of DOM and reading all the adjacent directories of blog posts to find code directories and show them in the code viewer component.

This made the process more complex. It also added a hidden cost of high maintenance to the project. Adding new features many months later won’t be as easy as it is probably going to conflict with the existing CSS or crash out the whole build process.

Should you build your own blog?

You probably should not develop your own blog from scratch if:

• you just want to write right from this instance
• you don’t care about customization, styles, or new features too much
• you want something working immediately

where it might make sense:

• you want full control
• you’re experimenting with frameworks
• the blog itself is part of the learning process

Closing thoughts

Long story short, I really like the end result. I have the blog template that I was dreaming of (mostly). The process had some errors and getting stuck situations that were unnecessary for a project like this but whatever. I don’t regret it and I think I’ve done a great job. I’ve eliminated all the excuses for not writing more.