Rationale

Like any sane developer, I created Squarkdown because I needed a tool to do something, but couldn’t find any that could.¹

The situation which led me to create Squarkdown should actually pretty clearly illustrate what it’s for. (I hope.)

So I store my personal wiki, Assort, as a repo on GitHub. It’s filled with hundreds of .md files stored in a meshwork of folders. You can browse through them right on GitHub, and GitHub renders a lovely preview with GitHub-Flavoured Markdown for each file. This is certainly my preferred way of reading their content!

At the same time, I also wanted to share the content with non-techy people who probably wouldn’t be accustomed to browsing content through a GitHub repo. In this case, a website would be ideal.

How and why I chose Svelte/Kit is irrelevant, but it’s my web dev framework of choice.

However, extracting the content from all those Markdown files to the Svelte site was… a little nontrivial, considering they were literally everywhere. Deeply nested folders, stored alongside other files, some hidden files that I didn’t want deployed… I wanted a huge degree of control over their processing.

What Squarkdown does is exactly that – it automates the process of collecting all the relevant .md files in the repo, processing and extracting their metadata, and generating their equivalent pages in the site. It means I can write content in Markdown as usual, then simply configure a few options in squarks, and have the peace of mind that it’ll all be automatically reflected in the site.

One of the most important points of the framework is that it should leave no visible artefacts on the Markdown – hence why everything is achieved through comments, which do not impact the displayed Markdown at all!