Motivation

This blog is presented to you by the usual suspects - the innate need to build your own tools, the addictiveness of coding for the web, and a lot of free time to kill after finals week. For years now, I've wanted to get into technical writing something. While I do maintain a Wordpress which is reserved for non-technical writing, I wanted my technical entries to be hosted on my own website. There's a few ways to achieve this, but I wanted to choose the path which could to the best of it's abilities mimic the easy to use UX that Wordpress provides, so that the friction between thought-to-words-to-push is as minimal as possible. In essence I wanted something that:

• Has its own dedicated editor instead of having to write using a .docx editor and then importing it.
• Comes with handy formatting options.
• Does not need a manual edit to post indexes.
• Has an option to save drafts, edit existing posts, change visibility etc.

Essentially, a very simple CMS, which can be run using a single npm run dev on your machine and updated using a simple git push origin main once you're done with your changes.

Why Markdown

Writing a frontend for a custom editor gave me intense war flashbacks from my time at LegalAI. At the time, one of my tasks was to build a "simple" interface for a editor similar to Google Docs which was secretly a template engine. The flow went something like this: A lawyer write up a legal document, you import it to the web app where you have easy options to add variables using the specifics of the case, you then save this to be used for their particular flows. Building this simple interface taught me three things: building software is complicated, RichText is a nightmare the libraries for which are not customizable requiring you to use very specific hacks to get it to work, and that building software is complicated when you are working with libraries that are for the most part an opaque blackbox. I wanted to get rid of all this complexity, and use something simple - Markdown. All the raw text doesn't need additional tooling to store, read, or parse. I am not a lawyer who is dependent on .docx or .pdf for writing my blogs. Converting raw Markdown to a displayable HTML is trivial.

FS as DB

Another aspect of this project that came in handy is the fact that it's hosted as a static site. While I do need to store all my drafts and published posts somewhere, it's not necessary for me to have the overhead of configuring and managing a Database when a simple set of queries to the Filesystem does the trick.

There exists a single index.json file that stores an array of all the posts that I have, and individual .json files that store each of the posts in a format similar to how .ipynb files are stored.

The user interface is similar to how a Jupyter notebook works too, there are independent cells that contain markdown, once you Shift + Enter, it parses the markdown to HTML so that you get a WYSIWYG experience.

Future Work?

• Polish up the UI to be more seamless, currently there are a lot of edge-case bugs with the CSS.
• Add support for images, and header images.
• Add support to import PDF or .tex files so that project reports can be more easily displayed.
• Use this blog enough to find out more quality of life improvements!

The source code for the blog specific part of the project can be seen here:

UI

Blog Engine APIs