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