English 丨 简体中文
A clean, elegant, feature-rich blog theme for Astro.
Build your personal blog with static pages, Markdown / MDX, light and dark modes, and a rich collection of content components.
Use this template · Documentation · Quick start · Configuration · Components · Deployment · Report an issue
- Layout and reading: responsive post cards, recommendations, sidebar, table of contents, related posts, copyright notices, and donation links.
- Writing: Markdown / MDX, 41 content components, Shiki syntax highlighting, and KaTeX math rendering.
- Post management: categories, tags, series, archives, pagination, pinned posts, drafts, custom URLs, and aliases.
- Special pages: About, Links, Equipment, Music, Message Board, short posts, Recent Comments, and 404.
- Interactions: light and dark modes, image lightbox, keyboard shortcuts, context menu, and a music capsule that persists across page navigation.
- Search and feeds: local search, Algolia, DocSearch, RSS, and sitemap.
- Comments: Twikoo, Waline, Valine, Artalk, and Giscus, loaded according to configuration.
- Interface languages: English by default, with Simplified Chinese, Traditional Chinese, and Spanish.
- Static deployment: generate static files for a hosting platform or your own server.
Install Node.js 22.12.0+ and pnpm. Use the pnpm version specified in the packageManager field of package.json.
Click Use this template to create an independent repository, then clone your copy (replace YOUR_NAME and my-blog):
git clone https://github.com/YOUR_NAME/my-blog.git
cd my-blog
pnpm install --frozen-lockfile
pnpm devOpen the local URL shown in your terminal to preview the theme and sample content.
Edit src/site.config.ts to set your site URL, title, author, navigation, and theme options. Here is a minimal configuration:
import { defineSolitudeConfig } from './lib/config';
export default defineSolitudeConfig({
site: 'https://example.com',
title: 'My blog',
description: 'Notes, stories, and discoveries.',
locale: 'en',
author: { name: 'Your name' },
});For a site hosted under a subdirectory, also set base, for example base: '/blog/'. See Configuration for all options.
The template includes sample posts and pages with local search enabled. Comments, comment aggregation, and the music hall are disabled with empty service identifiers. The music capsule is enabled with a sample Qishui playlist; replace theme.capsule.id with your own playlist or set theme.capsule.enable: false to disable it. Follow the integration guide to connect your own services. Replace sample content, images, and site identity before publishing. Changing the interface locale does not translate posts or custom navigation.
Create a Markdown or MDX file in src/content/posts/, such as hello-world.md:
---
title: Hello, world
date: 2026-09-11
description: My first post.
tags: [Life]
---
Start your story here.The default URL is /p/hello-world/. Use slug, url, and aliases to customize addresses. Set draft: true for drafts, or home: false to hide a post from homepage areas while keeping it in archives, search, RSS, and direct links.
See Front matter and MDX components for more writing options.
pnpm build
pnpm previewPublish the generated dist/ directory to your hosting platform. Set the build command to pnpm build and the output directory to dist. Use pnpm install --frozen-lockfile during dependency installation.
See Deployment for hosting instructions and path configuration.
The template, sample content, and documentation use English by default. Built-in interface translations are available in Simplified Chinese, Traditional Chinese, and Spanish. Start with the documentation index.
| Guide | Contents |
|---|---|
| Getting started | Create a template copy, install, write your first post |
| Configuration | Site identity, appearance, navigation, defaults |
| Writing | Front matter, drafts, categories, URLs, feeds |
| Pages | About, links, equipment, short updates |
| Components | Usage, parameters, and examples for all 41 MDX components |
| Integrations | Comments, music, external search |
| Deployment | GitHub Pages, static hosts, subpaths |
| Hugo import | Preview, export, verify migrated content |
| FAQ | Troubleshooting and theme updates |
More previews: dark mode and mobile reading
astro-solitude/
├── public/ # Images, fonts, and other static assets
├── src/
│ ├── components/ # Theme and MDX components
│ ├── content/
│ │ ├── posts/ # Blog posts
│ │ └── pages/ # Custom pages
│ ├── data/ # About, links, equipment, and short-post data
│ ├── layouts/ # Page layouts
│ ├── pages/ # Astro routes
│ ├── styles/custom.css # Custom styles
│ └── site.config.ts # Site configuration
├── docs/ # Documentation
└── astro.config.mjs # Astro configuration
Use Issues for bug reports and suggestions. Pull requests improving the theme, documentation, and translations are welcome. Include reproduction steps, your environment, and relevant configuration when reporting a problem.
Run these checks before submitting changes:
pnpm docs:check
pnpm check
pnpm build
pnpm testFor changes to page interactions, also run the browser tests:
pnpm build:fixture
pnpm exec playwright install chromium
pnpm test:e2eBrowser tests use an isolated fixture site. Mocked third-party tests do not establish that live services work. See the development validation report for test coverage and source comparisons.
Apache-2.0 License © 2026–present everfu. Retain the applicable license and copyright notices when modifying or redistributing the project.