Technical blog template

This is a template I wrote for my blog. I figured it would be useful to other folks too, so I'm releasing it into the public domain.

Live demo

Features

10 kB
Responsive layout
Auto blog post list
Auto table of contents
Auto RSS feed
Numbered sidenotes
Build-time syntax highlighting
Math typesetting
Markdown
Optional HTML & JS alongside Markdown for interactivity

Tech

This is built with Astro, with KaTeX for math rendering, and Tailwind for CSS. If these names mean nothing to you, no worries. :) The system does as much as possible at build time, producing small HTML and CSS files with no mandatory JavaScript.

Before this, my blog was built on Zola, which doesn't have a plugin system, and has its own quirky and limited component system. This new stack is a lot more programmable and allows me to use any of the great web libraries out there for syntax highlighting, Markdown parsing, and math typesetting. It also enables interactive content alongside the static HTML, with pretty standard components.

Set up

Install Node.js 14.18.0, v16.12.0, or higher.
Fork and clone this repo
From inside the repo, run npm install
Change the site URL in astro.config.mjs to point to your website. This is necessary for RSS feed generation.
Change the title and description in rss.xml.js.

Develop

While developing, run npm run dev, and access the website on localhost. It will refresh automatically when you make changes to the source. This is handy when writing blog posts in Markdown and seeing changes refresh in the browser automatically.

Deploy

When you're ready to deploy you have many options: