Black Sheep Code

I'm playing with Remix

I've recently converted this blog to a static-like site generated by Remix.

Before this (and it still is), the blog was a series of markdown files hosted on github, and that's it. Now, I can turn those markdown files into something a bit more palatable than the Github view of markdown files.

Philosophy of blogging - make sure you own the content

Remember when Medium.com was the place everybody was writing technical articles?

(FWIW, I loved the interface of Medium, the 'unlimited claps/clap as you read' feature was brilliant innovation that I personally, loved interacting with.)

But then Medium adopted a paywall model and the community died. If you had spent time and effort building up a portfolio of writing on Medium, you'd now need to port that to whatever the new hotness is.

In a similar vein, I ran a 'Humans of' photography Facebook page for several years in Wellington. I took a Facebook first approach, and I've long lost the original photos, so if I wanted to pull of the photos and quotes to move somewhere else, I'd have to be pulling them from Facebook.

Now of course, in both of these cases probably the data can extracted programmatically via API, but you may run into formatting issues, and just generally the whole thing sounds like a lot of friction.

The lesson in this is that while you may want to publish content to various platforms, it might be a lot easier to build an audience on one of these platforms, than on a personal blog, it's a good idea to own the original content in a format that you control.

So this had been the approach I'd taken, I started writing posts in markdown, (you can see other posts in other repos on my Github, for example, my TypeScript tutorial series here) and just left them in Github, and that's it, occasionally sharing links directly to the Github markdown preview.

I like markdown

I'm a fan of open standards.

In my ideal world, I could write blog posts in markdown, and if I chose to publish them on other platforms, they'd seamlessly publish there with no need for massaging.

A lot of platforms do adopt a markdown first approach. Github and Stack Overflow, Dev.to, only provide a markdown editor, and provide corresponding preview. Reddit uses markdown, but with a WYSIWYG editor as default and escape to markdown mode.

Medium does not support markdown natively, and you have to resort to convertors and workarounds.

The idea generally is, if I start building up a portfolio of content now in markdown, then this will future proof it for whatever platform will exist in the future.

Even if a platform does not support markdown directly, markdown is a widely enough used format that either someone would create a convertor, or I could existing markdown tooling to do the conversion myself.

Thoughts about server side rendering and static site generation

I have to confess, I've been reluctant to embrace SSR/SSG.

For the most part, I've taken a 'you ain't gonna need it' attitude.

Yes, of course an e-commerce website, with its need for good SEO on every listing, and the need to serve content to underpowered cellphones would get great value from SSR/SSG.

But a business application that is behind a login, and all the users are on a desktop? There's no SEO to be done, and so what if they download a big bundle when they first log in.

And there's a sense in which I feel like my reluctance is vindicated - remember when Gatsby was the React hotness?

Call me jaded, but I have to wonder if the developers maintaining commercial applications that adopted Gatsby five years ago are currently in a world of pain, as Gatsby appears to have lost the game to Next.js and Remix.

(I did have a brief play around with Gatsby five years ago and ran into flash-of-unstyled-content type issues when using it Material-UI; I didn't have a particularly fun time of it).

With all that said:

  1. It's good to stay on top of things.
  2. If Remix is going to help make the difference between 'a working app' and a 'oh wow, this is snappy!' app, it's a tool worth having in my tool belt.
  3. For a blog SEO is important.

Using Remix to create a markdown-based blog

With Remix's file based routing, having my markdown files convert into routes within an Remix application should be straightforward (spoiler alert: it is).

Remix supports MDX out of the box.

This means that I just needed to rename my posts from .md to .mdx and Remix started serving them as routes.

Configuring the MDX rendering

It being a technical blog, I frequently post code snippets via the triple backtick syntax.

Remix provides a guide for configuring this how the MDX is rendered here. Specifically for code syntax highlighting, rehype is used.

You can see the configuration I've used at time of writing here (adding the rehype plugin) and here (adding rehype styling).

Creating a table of contents

The next thing I wanted was if you reach the home page, I wanted links to each individual blog post. I didn't want to have to maintain this list of links manually, I wanted those to be generated by just what's in the routes folder.

I was surprised the remix doesn't actually support this out of the box. There's a few posts relating to 'creating a static blog using remix', but I ultimately rolled my own script to generate a table of contents.

Essentially the technique is:

  1. I have a node script that examines the routes/posts folder and creates a single file ListOfArticles.tsx - containing a link to each blog post.
  2. The component ListOfArticles is used in routes/index.tsx
  3. I edit the build script in the package json to generate the ListOfArticles.tsx before building the remix bundle.

The approach is rudimentary, I currently don't have a way to display better titles for example, the link titles just show the underscores, but this is something I'm looking at solving with Front Matter tooling.

What's Next?

Aside from continuing creating blog posts, the priority is to make this more like a proper blog.

Some features I want to add:

Spotted an error? Edit this page with Github