Writing and maintaining a blog hasn't historically worked well for me - blogs tend to feel too static and too high-pressure. I love to write and document though! I resonated with Matt Newkirk's philosophy of You don't need to blog to practice your writing in large part because traditionally I have done most of my writing for work and not in the public sphere, but there's a select few things that I think could transfer well.
As an approach and structure for all this, I've been enamored with the idea of growing a garden ever since reading Maggie's essay - I love the imperfection of it all and the expectation of growth and change. The writing here will be well-formed at times, and draft-at-best at other times. At the time of writing, I've had two posts that I've published and revisited repeatedly as I refine my thinking and it feels great to do so.
With those expectations set, let's dive into some bits about this garden!
Tradeoffs
A. Roll my own > existing platform
My site has been a single static page for years, and every year I make the decision to not add to it for simplicity, but today's the day! This tradeoff falls under the "because it's fun" clause.
B. Boring technology1 & comfort > building robust
- Use the same tech that the rest of the site uses when possible: Tailwind CSS / Next.js / etc.
- Doesn't add additional services like a publishing platform / CMS - it's all stored in-repo.
- It's written in Markdown in a text editor (this is how I write all my notes)
C. Future-welcome >= hacked together
Some upfront diligence is worth it so if I have something that doesn't fit the traditional blog mold, I don't have to throw it all out. This garden is statically generated from mdx files, which means that I could go fancy and embed React into my posts, or write a whole post in HTML, or never use that functionality and just write Markdown!
D. Shipped >>> not
The reader does not care if I manually type the whole darn thing out, just that the content is there. This means some data is manually updated by me (see: updated_at), because it's the quickest path to publishing.
Getting started
This is an entirely local, MDX-based garden. The pages are just pages in Next.js - the full contents of this page, including references to generic header and footer components, is located in my project at /pages/garden/about-this-garden/index.mdx.
Typing & metadata
I grabbed the directory structure and some metadata inspiration from the Tailwind blog post about creating a blog with Next.js and Tailwind CSS, but I found the post management a bit gnarly, so I just added typed exports to my pages and called it a day instead of diving into webpack. With this very-local MDX approach, I do think Gatsby's less opinionated Node APIs may have been a bit quicker and I found myself wishing just a little bit that I had instead just used a CRM coupled with Next.js Dynamic Routes. For the curious, the type exports/imports look a little something like this:
// types/mdx.d.ts
declare module "*.mdx" {
export type GardenMeta = {
slug: string;
title: string;
...
};
export const meta: GardenMeta;
let MDXComponent: (props: any) => JSX.Element;
export default MDXComponent;
}
// pages/garden/index.tsx
import { meta as meta1 } from "./about-this-garden/index.mdx";
import { meta as meta2 } from "./tailwind-preflight/index.mdx";
const postMetas = [meta1, meta2].sort((a, b) =>
a.started_at < b.started_at ? 1 : -1
);
// And so on ...
This premise is what powers the snazzy garden index.
Styling
The Tailwind blog was useful, but (ironically?) didn't mention styling. For that, I leaned on the Next.js docs on integrating with MDX and ended up having to do some very basic, but necessary, styling via the MDXProvider.
You can read more about this here.
Footnotes
1: "boring" as in Choose Boring Technology