Astro Citrus

Astro Citrus is an opinionated Astro v5 starter template for building a blog or static website, created by Artem Kutsan.

What is Astro Citrus?

Astro Citrus is a free, MIT-licensed open-source starter template built on Astro v5. It takes Markdown and MDX files from src/content/post and src/content/note folders and generates a static blog or website with an automatic RSS feed, sitemap, robots.txt, and web app manifest. The template uses content collections with a typed frontmatter schema in src/content/config.ts to validate post metadata at build time.

Key Features

• Astro v5 core — Built on Astro v5 for fast static site generation, with pnpm commands for install, dev server, production build, preview, and type generation.
• TailwindCSS utility classes — Styling uses TailwindCSS, with light/dark mode via CSS variables and custom themes editable in src/styles/global.css.
• MD & MDX content — Supports Markdown and MDX posts and notes, including Admonitions (callouts) and syntax-highlighted code blocks via Rehype Pretty Code.
• Satori Open Graph images — Automatically generates PNG social-sharing images for posts using Satori, or lets you provide your own ogImage in frontmatter.
• Pagefind static search — Integrates Pagefind for client-side search of posts and notes, with a postbuild script and optional tag filtering.
• Webmentions and social links — Includes webmention.io support and Astro Icon for adding SVG icons to social links in SocialList.astro.
• SEO and performance — Provides accessible, semantic HTML, responsive design, and automatic sitemap/robots.txt generation.

Who is it for?

• Bloggers and content writers — publish by dropping .md or .mdx files into src/content/post; the theme handles RSS, OG images, tags, series, and drafts.
• Developers seeking a minimal setup — clone the repo or run pnpm dlx create-astro --template artemkutsan/astro-citrus to scaffold a fully working site in minutes.
• Designers who want to customize — change colors and fonts in src/styles/global.css and Tailwind classes; modify the Satori markup for custom OG image styles.
• Open-source maintainers — use it for project documentation or a personal site, with one-click deploy buttons for Netlify and Vercel.

What can you do with Astro Citrus?

• Personal bloggers: write long-form posts with optional cover images, series grouping, tags, and draft status; the template generates a searchable, SEO-friendly site.
• Technical writers: create MDX posts with Rehype Pretty Code highlighting and markdown admonitions; include webmentions to connect with the indie web.
• Indie web enthusiasts: enable webmention.io integration and add social links with Astro Icon to display your profile across platforms.
• Site builders: customize src/site.config.ts and deploy to any static host; the README links to Astro's deployment guide and platform-specific analytics options.

How does Astro Citrus work?

1. Create a repo from the template or run pnpm dlx create-astro --template artemkutsan/astro-citrus.
2. Install dependencies with pnpm install, then run pnpm dev for local development at localhost:3000.
3. Customize src/site.config.ts and astro.config.ts (set the site property), and replace favicon and social card images in /public.
4. Add posts to src/content/post/ and notes to src/content/note/ with required frontmatter.
5. Build with pnpm build, then run pnpm postbuild to generate the Pagefind search index.

FAQ

Is Astro Citrus free?

Yes, Astro Citrus is released under the MIT license. You can use it freely for personal or commercial projects.

What frontmatter is required for a post?

Posts need title (max 60 chars), description (50-160 chars), and publishDate in ISO 8601 format. Optional fields include updatedDate, tags, coverImage, ogImage, draft, seriesId, and orderInSeries.

Does Astro Citrus include analytics?

No built-in analytics are included. You can add your own analytics snippet (e.g., Vercel, Netlify, or Cloudflare Web Analytics) in src/layouts/Base.astro or src/components/BaseHead.astro.

How do I update the template?

If you forked the repo, use GitHub's "sync fork" feature. If you created a template repository, add this template as a remote and pull changes, being careful not to overwrite your custom content.

Can I use Astro Citrus for a non-blog site?

Yes, the repository notes it can be used to create an "easy-to-use blog or website." You can create extra pages beyond posts and notes, and Pagefind search can be extended to include all pages by moving the data-pagefind-body attribute.