Astro Solitude is an Apache-2.0-licensed blog theme for the Astro framework that compiles Markdown and MDX posts into a static personal blog, maintained by everfu and configured through one typed TypeScript file.
What is Astro Solitude?
Astro Solitude is a static blog theme built on the Astro framework, published by everfu under the Apache-2.0 license. Its input is Markdown or MDX files placed in src/content/posts/ with YAML front matter (title, date, description, tags, slug, url, aliases, draft flags), plus a single configuration file at src/site.config.ts written through the defineSolitudeConfig helper. Its output is a dist/ directory of pre-rendered static files you can drop on any hosting platform or your own server. The repo ships sample posts, sample pages, eight documentation guides, and screenshots for desktop and mobile reading.
What makes Astro Solitude stand out?
- Astro-based static output — the theme builds to plain static files; set the build command to
pnpm build and the publish directory to dist, with an optional base value for sites hosted in a subdirectory.
- Markdown and MDX authoring — posts support Shiki syntax highlighting, KaTeX math rendering, and 41 documented MDX content components with parameters and examples.
- Post management — categories, tags, series, archives, pagination, pinned posts, drafts, custom URLs through slug and url, and aliases for redirects;
home: false keeps a post out of homepage areas while leaving it in archives, search, RSS, and direct links.
- Reading layout — responsive post cards, recommendations, sidebar, table of contents, related posts, copyright notices, and donation links.
- Special pages — About, Links, Equipment, Music, Message Board, short posts, Recent Comments, and a 404 page.
- Interactions — light and dark modes, image lightbox, keyboard shortcuts, context menu, and a music capsule that keeps playing across page navigation.
- Search, feeds, and comments — local search plus Algolia and DocSearch, RSS and sitemap output, and Twikoo, Waline, Valine, Artalk, or Giscus comment backends loaded from configuration.
- Interface locales — English by default, with built-in Simplified Chinese, Traditional Chinese, and Spanish translations.
Who should use Astro Solitude?
- Personal bloggers who already write in Markdown or MDX and want a static, self-hosted blog with archives, tags, series, and an RSS feed.
- Developers moving off Hugo — the repository includes a migration guide with preview, export, and verification steps for imported content.
- Writers who want reader features already wired up — tables of contents, related posts, light and dark modes, image lightbox, and keyboard shortcuts ship with the layout.
- Site owners adding community — switch on Twikoo, Waline, Valine, Artalk, or Giscus by supplying service identifiers instead of building comment UI.
What can you do with Astro Solitude?
- Technical writers: publish MDX posts containing KaTeX equations, Shiki-highlighted code, and MDX components, then ship the static
dist/ folder to GitHub Pages or any static host.
- Community builders: enable a comment backend, a message board page, and Recent Comments so readers can reply without leaving the site.
- Multi-language authors: set the interface locale to Simplified Chinese, Traditional Chinese, or Spanish while keeping posts in whatever language you write.
- Migrators: import an existing Hugo site and verify the migrated content before publishing, then replace the shipped sample content, images, and site identity.
How does Astro Solitude work?
- Create an independent repository from the template, clone it, and run
pnpm install --frozen-lockfile followed by pnpm dev on Node.js 22.12.0 or newer.
- Edit
src/site.config.ts with your site URL, title, description, locale, author, navigation, and theme options, adding base for subdirectory hosting.
- Add Markdown or MDX files to
src/content/posts/, then run pnpm build and pnpm preview before publishing.
Pros and cons
- Free and open source under Apache-2.0, with static output that needs no server runtime.
- Five comment backends and three search options are supported from configuration.
- Comments, comment aggregation, and online music are disabled out of the box with empty service identifiers, so you must connect your own services.
- Changing the interface locale does not translate posts or custom navigation, and the bundled sample content must be replaced before publishing.
- Development requires Node.js 22.12.0 or newer and the pnpm version pinned in the
packageManager field.
FAQ
Is Astro Solitude free?
Yes. Astro Solitude is released under the Apache-2.0 license, copyright everfu, and you can modify or redistribute it as long as you retain the applicable license and copyright notices.
It supports Twikoo, Waline, Valine, Artalk, and Giscus, each loaded according to configuration. They ship disabled with empty service identifiers, so you need to supply your own service details before comments appear on posts.
What do I need to run Astro Solitude?
Node.js 22.12.0 or newer and pnpm, using the version pinned in the packageManager field of package.json. The theme builds static files, so the final site needs no Node.js runtime on your host.
Can I use Astro Solitude for a blog in a subdirectory?
Yes. Set the base option in src/site.config.ts, for example /blog/, and the generated links and assets are built for that path. The deployment guide covers subpath configuration for static hosts.
What is the default URL for a post?
A post at src/content/posts/hello-world.md is published at /p/hello-world/ by default. You can override the address with the slug or url front matter field, and add aliases to keep old links working.
