I Don't Style Markdown by Hand — I Let @tailwindcss/typography Do It

Every piece of content on this site — blog posts, portfolio case studies — is written in Markdown and rendered into raw HTML: h2, p, ul, blockquotes, code blocks, all sorts of elements I don’t always remember show up where. I don’t hand-write CSS for each of those elements, and I deliberately don’t want to.

Before installing this plugin, I actually tried styling things manually for a few days early in this site’s build. The result was exactly what you’d expect: h2 headings looked fine, but the moment a post had a nested list (a list inside a list), the spacing fell apart because I’d forgotten to handle margins for nested elements. Then one post needed a comparison table, and it rendered with no border at all because I’d never accounted for that element showing up. Every time I hit one of these, I had to go back and patch the CSS, and that turned into a recurring pattern every time I wrote a post with a slightly different structure than usual.

The fix

The @tailwindcss/typography plugin, loaded via @plugin "@tailwindcss/typography" in global.css — in Tailwind v4 this is different from how plugins were registered in v3, which still used a tailwind.config.js file, but the concept is the same. I just wrap the rendered markdown output in a prose class inside BlogPostBody.astro and PortfolioDetailBody.astro, and the plugin handles everything: heading hierarchy, paragraph spacing, lists (nested or not), blockquotes, inline code, even tables — consistently across every post, without me writing a single line of custom CSS for it.

Why not just style it myself

Because the content is free-form markdown, I can’t predict which elements will show up in a post I write next month. Hand-styling per component means I’d inevitably miss something rarely used — which I already proved to myself with the nested list and the table — and it would render broken the one time that element actually gets used, usually while I’m rushing to publish something and don’t check the preview carefully.

What I still customize

Just link color and accents, to match this site’s --color-primary, through extra classes like prose-a:text-primary and a few similar modifiers on headings. Everything else stays default, because the plugin’s defaults are already readable enough in both light and dark mode — I checked both manually when I first installed it and didn’t find any meaningful contrast issues.

An effect I didn’t notice right away: since installing this plugin, I’ve gotten more willing to write markdown with more varied structure — nested lists, comparison tables, blockquotes for quotes — because I know it’ll all render cleanly without me having to rethink the CSS every time. Sometimes the most efficient solution isn’t writing code yourself — it’s picking a plugin that already solved the same problem for thousands of other sites before you try solving it from scratch.