Project / init

I built a place to write about things I’m figuring out how to build

  • Markdown Extended
  • DNS
  • Firebase
  • Web
  • Astro
Status
Production
Platform
Web
Language
MDX

I’ve had the idea of making a personal site for a while.

Not particularly because I needed a portfolio. I already have a CV, a GitHub profile, and the usual collection of links that tend to make up a developer’s online presence.

What I wanted was a place to write about the things I actually spend my time doing, from things I want to try out to the projects that start with “I wish I could just do it myself” and end with experience and questionable results.

So, here we are.

Why an Engineering Notebook?

I’ve been thinking about the various ways people document their projects online. Some people write their own blog post on X, others share on Medium.com or dev.to, and others still have a personal site with a blog. None of those felt quite like what I was looking for. I wanted a place where I can work with tools that are familiar to me, without being limited by platform restrictions.

While looking for different ways to document my projects, I came up with the following list of requirements:

  • It needs to be easy to write

    The WX needs to be excellent. I don’t want to be fiddling with CSS and colors etc. during the time I dedicate to writing.

  • Writable with Markdown

    For obvious reasons, such as:

    1. Markdown is awesome
    2. No further reasons needed

  • Customizable with MDX

    I love React, and the idea of being able to embed components into a Markdown document is quite appealing.

  • 100% Mine and Customizable

    I don’t want the styles, components, or themes to be constrained by whatever platform I choose. For example, if I were to post on Medium.com, I wouldn’t be able to embed a live component inline; I’d need to host it externally.

    With MDX, I can drop an interactive component directly into the content:

    0

    All I need to write for that is:

    - [x] 100% Mine and Customizable

    I don't want the styles, components, or themes to be constrained by whatever platform I choose.
    For example, if I were to post on Medium.com, I wouldn't be able to embed a live component inline;
    I'd need to host it externally.

    With MDX, I can drop an interactive component directly into the content:
    <Counter client:visible />

The Implementation

To meet these requirements, the infrastructure is relatively straightforward:

  • Framework: Astro for the static site generation and native MDX support.
  • Components: React for interactive elements.
  • Deployment: Firebase Hosting.

Setting this up was not without the usual headaches that come with learning how to use new tools. I spent a frustrating few minutes trying to figure out why my MDX was getting rendered as raw Markdown before realizing that I had saved this file as first-post.md instead of first-post.mdx 🤦‍♂️.

Once I fixed the file extension, the components still failed to load because I was importing from @/components instead of @components, the alias I configured for src/components/ui in tsconfig.json.

These are trivial mistakes, but they are exactly the kinds of friction that consume actual development time, and are part and parcel of the learning curve when adjusting to a new toolset.

Even as I was writing the above paragraph, I wanted to include the :man_facepalming: emoji, but to my surprise, emoji shortcodes were not bundled by default in Astro. I went to check which Markdown plugin I needed, and found remark-gemoji.

After installing and configuring it in astro.config.mjs, I was presented with the following error message:

Astro Error
14:22:33 [ERROR] [config] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` run
on the `unified` processor from `@astrojs/markdown-remark`, which is no longer installed by default now that
Satteri is the default Markdown processor. Install it with:
npm install @astrojs/markdown-remark
Stack trace:
  at /Users/benjitusk/GitHub/astro-blog/node_modules/astro/dist/core/config/validate.js:56:3
  [...] See full stack trace in the browser, or rerun with --verbose.

A bit of research revealed that in v7.0, Astro migrated from the JS-based unified Markdown pipeline to the Rust-based Sätteri pipeline. Because of this, many plugins had to be ported over, and I found the satteri-emoji plugin to be a satisfactory replacement.

I also had some trouble when trying to verify the domain for Firebase Hosting. I found out that if you enable Cloudflare’s domain proxying service, it doesn’t publish the records normally. The actual records are served by cloudflare, and your domain just gets an A record pointing to Cloudflare’s services. After disabling the Cloudflare proxy, the domain verification went through within a couple of minutes.

Some of the other customizations I needed to make while writing this article were:

  • Setting up a callouts plugin and adding a custom callout for console output, along with custom styling for all the other callout types:

    Sample console output
    A very real console
    Hello world!

  • Overriding the default Astro font provider and configuring my own.

  • Setting up integration with shadcn components, so I can just pull from their registry instead of having to build my own components from scratch.

Documenting Failure and the Unknown

Standard technical blogs usually present a sanitized version of development, following a very dry arc:

  1. A problem is presented
  2. A clean solution is proposed
  3. The implementation is executed flawlessly

As anyone who develops software knows, this is rarely how it actually goes. The most insightful technical information often comes from the failures, dead ends, and integration hell.

This site is not intended to showcase my completed projects; it’s an engineering notebook. I’ll be writing about things while I’m still trying to figure them out, instead of waiting to publish the sterilized implementation when it’s complete. Failure and uncertainty are the very things I want to highlight as I document each project.

What belongs here

  • Incomplete Prototypes: Ideas that are functional but not production-ready.
  • Debugging Sessions: Step-by-step logs of tracking down obscure bugs, specifically when the root cause contradicts initial hypotheses.
  • Reverse-Engineering Logs: Attempts to understand how an undocumented API or system operates, regardless of whether the attempt succeeds.
  • Whatever the heck else I want to write about: I mean, it’s my notebook, after all. I can doodle if I want to 😉.

Conclusion

The infrastructure for the site is configured, the MDX pipeline works, and the CI/CD is functioning. Well, not yet, but presumably if you’re reading this, then I’ve figured it out by now. The initial setup is out of the way, which means I can start writing about actual projects.