Posted on 12/11/2024

When I decided to build this blog, I wanted it to truly feel like mine and to create a platform that gives me full independence, stands the test of time, and offers the freedom to include anything I want - from live code examples to fun visuals.

Let's dive into why I over-enginered this blog!

While building a blog on an existing blogging platform is a great choice to easily start and get eyes on what you write, they can change over time and you might not be aligned with the way they use your content to remain a sustainable business.

Medium is the best example that comes to my mind, several years ago most of the technical posts I was learning from were posted there - but then giant popups started to appear as well as limits on the number of articles you can read for free.

The kind of paywall I never want in front of my free articles!

This experience has taught be that if I want to be safe from such changes, I need to own the hosting platform.

This being said, it's still possible that I'll use my dev.to account to cross-post a bit and see how it goes - as it should help reaching a larger audience in the early stages. I only posted once there, but the audience I reached was far beyond what I had imagined.

Long-term plan is to stop doing that though, as here I'll have full freedom on the experience I want to provide through my embeddings.

What drove me to work in that field is the joy of being able to build high quality, satisfying experiences and this blog is no exception! Providing the best experience to explain technical concepts can only go so far with static text.

There are many ways one would want to embed code samples in a post. This blog covers a great variety of them, from quick inline code to fully editable sandboxes.

This one is the most straightforward - when I want to quickly write some lines of code or embed a JSON, I want to be able to do so inline, directly in the MDX file:

function getHello() {
  return "Hello!";
}

I wrote this chunk of code in MDX using the backticks syntax

Now comes a more interesting problem: writing code in a static file sucks, because you have no IDE assistance and you cannot execute your code to assert that it works! And that's why there are tons of posts online with code samples that just don't work 💥

I solved this problem by making an InlineFile component that will read a file content and inline it as if it had been written directly in the MDX file like above.

export function fibonacci(num: number): number {
  if (num <= 1) {
    return 1;
  }

  return fibonacci(num - 1) + fibonacci(num - 2);
}

This file is imported directly in the MDX file

<InlineFile lang="typescript" filepath="./code/fibonacci.ts" />

I can simply use InlineFile to embed this code in the post

This allows me to write the code as if it were part of my project - I have all the devX tools to help (TypeScript, Prettier...), I can import the code in any page, make a storybook story for it, write tests...

Besides, since the blog is in MDX I can also decide to execute the code inline!

I actually wrote Result of fibonacci 10 = **{fibonacci(10)}** in the file

Last but not least, I sometimes want to provide an interactive code sandbox playground for you to toy with the code and get instant feedback on it.

I can import whichever code sample I want and make it run in this page!

This being said, I find making such interactive examples still quite a chore, so I might use them very sparingly and only when it really makes sense.

Considering other options (cloud or self-hosted CMS) I realized that assets management was always involving some sort of big tradeoff: either you pay someone to host them & manage them for you forever (eg. nope), or you have to maintain a database and schedule backups (eg. eww 😵).

I don't like very much the devX experience of embeding an image in an MDX file using VSCode, but I love the fact that it is very simple to manage (no database, no hosting, no migration!).

Besides, NextJS makes it so that images are well optimized for various screen sizes by default when built statically, which is exactly what I intend to do.

Found this nice photo from Daniel K Cheung on Unsplash

I've considered using tools such as mermaid.js or React Flow (which are very good and extremely powerful) but I'm not fan of the added complexity it introduced to my writing flow. I want something dead simple and closer to a whiteboard session experience. One might say, something less over-engineered 😅?

For this, as you can guess, Excalidraw is a very good fit! When I want to add a drawing to my post, here's what I do:

• Create <my-draw-name>.excalidraw file next to the post file
• Open it with VSCode (thanks to Excalidraw extension), draw whatever I like
• Export to PNG and use it as an image

This drawing is an excalidraw export

While I initially wanted to start with a "hands on" solution that does everything for me, thinking that it would make me win time and be more efficient, it actually pushed me away from writing and feeling implicated in doing it!

Trying to maximise output efficiency to what I want to be an after-work hobby turned it into a chore. So I decided to get my hands dirty and unreasonably push all the cursors I wanted to push, seeking for pleasure rather than strict output efficiency.

I have a growing conviction that, as a reader, you'll also feel the joy I had in creating this blog and its posts. In the process, I secretly hope it brings you joy as well — and maybe even sparks your curiosity to learn how I technically built this blog next 👀.