Minimal Blog

Astro Theme: Minimal Blog

Astro Theme: Minimal Blog is an open-source Astro starter theme by LekoArts that ships everything you need to run a static blog, including MDX authoring, live code playgrounds, and search.

What is Astro Theme: Minimal Blog?

Astro Theme: Minimal Blog is a GitHub-hosted theme for the Astro framework. It takes blog posts written in MDX with YAML frontmatter and renders a fully static website with RSS, sitemap, tagging, and search. The theme is designed by LekoArts, and the repository includes a demo site and a CLI for scaffolding posts.

Key Features

• MDX blogging — Write posts in MDX with frontmatter fields for title, slug, description, date, lastUpdated, tags, searchIndex, and an absolute image URL.
• Tailwind styling — The UI is styled with Tailwind CSS, giving you utility-first classes with no separate CSS framework.
• Expressive Code — Code blocks are rendered with Expressive Code, a syntax highlighter with advanced annotations like line highlighting and tabs.
• Custom asides — An Aside component supports note, caution, tip, and danger directives through MDX, letting you embed callouts in posts.
• Sandpack playground — A Playground component uses Sandpack to embed live, editable React code examples directly in your blog posts.
• RSS and sitemap — Built-in feed and sitemap generation are included, so your blog is ready for syndication and search engines.
• Tagging system — Posts can reference tags stored in a FRONTMATTER_TAGS map; display names appear in the UI while slugs drive tag URLs.
• Pagefind search — Static site search is provided by Pagefind, allowing readers to search your content without any server component.
• Color mode toggle — A built-in light, dark, and system color mode switcher adapts the site to the reader's preference.

Who is this theme for?

Developers who are comfortable with pnpm and Astro can clone the repository, install dependencies, run pnpm dev, and customize the theme through constants.ts. Content writers who prefer writing in Markdown or MDX can use the pnpm assistant CLI to scaffold posts with the required frontmatter. Anyone deploying a static blog gets RSS, sitemap, and Pagefind search without setting up a backend.

What can you do with it?

• Publish a personal blog — Author MDX posts with code blocks and interactive examples, organize them with tags, and give readers fast, on-site search.
• Build a technical documentation site — Use the Aside callouts for notes and cautions and the Sandpack playground to show live code, then deploy the static output anywhere.
• Learn Astro patterns — As a minimal theme, it demonstrates content collections, custom MDX components, and a CLI script for content creation.

How does the theme work?

After cloning the repository, you install dependencies with pnpm install and start the local dev server with pnpm dev. The constants.ts file holds the site title and navigation, while the assistant.ts script powers a CLI that walks you through creating a new post. Tag definitions live in the FRONTMATTER_TAGS map inside constants.ts.

FAQ

How do I create a new blog post?

Run pnpm assistant in the project root. The CLI asks you questions to fill out the frontmatter and then creates a new post file for you. If you need to extend the behavior, the script at scripts/assistant.ts is editable.

How do I change the site title or navigation?

Look at src/constants.ts. This file sets the site title and main navigation, and it also holds the FRONTMATTER_TAGS map for tags. Modify those values to match your site before deploying.

How do I add a new tag?

In constants.ts, add an array pair to the FRONTMATTER_TAGS map with the display name and a slug, for example ['Display name', 'slug-of-your-tag']. The display name appears in the UI and the slug is used in URLs.

Does the theme support search?

Yes, Pagefind is integrated for static search. It works without any server, and the theme includes a search UI that scans your built pages.

What frontmatter fields are available?

The default content collection includes title, slug, description, date, lastUpdated, tags, searchIndex, and image. To adjust these, edit content.config.ts in the project.