I am a technical writer. My blog is, first and foremost, a place for text. That constraint made the theme decision easier than it might otherwise have been.
When I opened the AstroPaper demo, two things stood out immediately: the typography and the dark mode. The type was readable and well-spaced without trying to make a statement about itself. The dark mode looked like it was designed as a first-class option, not toggled on as an afterthought. Those two things were enough to make me look closer.
What I found when I looked closer was that AstroPaper came with more than I had bargained for. RSS feed out of the box. Full-text search, client-side, no backend required. Tag support. Pagination. An accessible, well-structured HTML output. For a theme that cost me nothing, it covered everything I would have had to build myself with a more minimal starting point.
The customization surface is also reasonable. The theme uses a small set of CSS variables for colors, which made it straightforward to adjust the palette. The Astro component structure is readable if you need to change something. I did need to change a few things.
The first surprise: dark mode is defined in two places. If you only change src/scripts/theme.ts, the default light mode flashes on load before the script kicks in. You also need to set the default in src/layouts/Layout.astro. Miss one of them and you get a flash of the wrong theme on every page load.
The second: AstroPaper does not display the author name on post cards or post detail pages by default. It is in the frontmatter, it is available, but the theme does not render it unless you add it to Card.astro and PostDetails.astro. A small change, but one you have to know to make.
The third: if you are writing in Croatian or any language that uses Latin Extended characters, you need to add "latin-ext" to the font subsets in astro.config.ts. Without it, characters like č, š, ž, ć, đ fall back to a system font mid-sentence, which looks exactly as bad as it sounds.
// astro.config.ts
fonts: [
{
provider: "fontsource",
name: "IBM Plex Mono",
subsets: ["latin", "latin-ext"],
},
]None of these were blockers. They were the kind of thing you fix once and then forget about, which is the best kind of problem to have.
AstroPaper is actively maintained, has a clear changelog, and the GitHub issues are responsive. For a personal blog built on Astro, it was the obvious choice once I saw it. The typography and dark mode were the hook. Everything else was the reason to stay.