Chirping Astro

Chirping Astro is a single-template, multilingual Astro v7 blog theme for technical writers, built with Tailwind CSS v4, daisyUI v5, MDX, Pagefind search, Giscus comments, and KaTeX math. It generates a fully static site with a minimal JavaScript footprint, ideal for documentation-heavy personal blogs.

What is Chirping Astro?

Chirping Astro is an open-source (MIT) Astro v7 theme inspired by the Chirpy Jekyll theme. It takes Markdown and MDX content organized in src/content/posts/ by locale and outputs a statically generated blog with RSS feeds, sitemap, search index, and automatic Open Graph images. The theme is maintained by a community on GitHub and designed to run with Bun as the package manager and runtime.

Key Features

• Astro v7 + Content Collections — Zod-validated frontmatter with required title, description, and pubDate; strict TypeScript.
• Tailwind CSS v4 + daisyUI v5 — Custom chirpy-light and chirpy-dark themes with OKLCH color tokens, no-FOUC theme toggle with View Transitions API animation.
• Expressive Code — Syntax highlighting with frame titles, copy buttons, line markers, diffs, collapsible sections, raw HTML, and daisyUI alerts from fenced code blocks.
• KaTeX math — Build-time pre-rendering; the KaTeX stylesheet (~29 kB) is only loaded on pages with math: true in frontmatter.
• Mermaid diagrams — Native rendering via the Sätteri plugin; the client library is bundled and injected only on pages with mermaid: true.
• Pagefind search — Lazy-loaded static search (modal + dedicated /search/ page) with locale filtering; search only works after bun run build, not in dev.
• Giscus comments — GitHub Discussions-based commenting with theme and locale sync; per-post opt-out via comments: false; a setup notice appears when placeholders are detected.
• i18n — English at the URL root and French under /fr out of the box; translation pairing via translationKey; partial translations supported with conditional hreflang and language switcher filtering.

Who is it for?

• Technical writers who want a statically generated blog with first-class i18n and dark mode, without building a theme from scratch.
• Developers who want to publish documentation or a personal blog using Markdown/MDX with code highlighting, math, and diagrams.
• Open-source maintainers who need a fast, accessible blog with comments (Giscus), search (Pagefind), and automatic OG images, deployed to GitHub Pages, Cloudflare Pages, Netlify, or Vercel.

What can you do with Chirping Astro?

• Bilingual blogging: Publish posts in English and French with shared translationKey; the language switcher lands readers on the equivalent article, and hreflang alternates are emitted only for available translations.
• Math-heavy writing: Write LaTeX math in Markdown/MDX with $...$ and $$...$$; KaTeX renders at build time and no JavaScript ships to the client.
• Diagram-rich posts: Include Mermaid diagrams by setting mermaid: true; the library is bundled locally and excluded from all other pages.
• Managed deployment: Deploy the static dist/ output to GitHub Pages with a pre-configured workflow that auto-detects BASE_PATH and SITE_URL, or to Cloudflare Pages/Netlify/Vercel with a few environment variables.

How does Chirping Astro work?

1. Clone the repository and run bun install.
2. Copy .env.example to .env and set SITE_URL and optional PUBLIC_* handles.
3. Edit src/config.ts to customize site identity, navigation, socials, and layout.
4. Write posts as .md or .mdx files in src/content/posts/<locale>/.
5. Run bun run dev to preview locally, or bun run build to generate the static site with the Pagefind index.

Pricing

Chirping Astro is free and open source under the MIT License. The companion starter template (chirping-astro-starter) is also freely available.

Alternatives

• Chirpy Jekyll — the original Jekyll theme that Chirping Astro is inspired by; it uses Ruby/Jekyll rather than Astro.

FAQ

Does search work in development?

No. Pagefind search only works after running bun run build, because the index is generated at build time into dist/_pagefind/. The dev server (bun run dev) will show a "Search index not available" message in the modal.

How do I enable math on a post?

Add math: true to the post's frontmatter. The KaTeX stylesheet — about 29 kB — is then loaded only for that page; other pages stay lean. Math is pre-rendered to HTML at build time, so no client JavaScript is needed.

Can I disable comments on a single post?

Yes. Set comments: false in the post's frontmatter, or disable Giscus globally by setting PUBLIC_GISCUS_ENABLED=false in your .env file. When Giscus is enabled but the repository IDs are still placeholders, the theme shows a setup notice instead of a broken iframe.

What locales are supported out of the box?

English (at the URL root) and French (under /fr). You can add more locales by extending SITE.locales in src/config.ts, adding a locale block in src/i18n/ui.ts, and creating the corresponding content and page folders.

Can I use npm or pnpm instead of Bun?

Bun is the only package manager and runtime assumed by the theme's scripts and CI. The lockfile is bun.lockb. npm, pnpm, and yarn may work but are untested.