CitrusGrid

CitrusGrid (柑橘格子) is an Astro-based static blog theme with a citrus-orange (#E86233) accent and grid-paper background, turning Markdown files with YAML frontmatter into a pre-rendered blog you can host on any static platform.

What is CitrusGrid?

CitrusGrid is a static blog theme built on Astro that converts Markdown posts with YAML frontmatter into a pre-rendered site, using a citrus-orange (#E86233) primary color and a squared draft-paper background. It is published by GitHub user rightdoor (repository rightdoor/citrus-grid), requires Node.js 22.14.0 or newer and Astro 7.2.9 or newer, and installs dependencies with pnpm. Site-wide options live in a single TypeScript file, src/site.config.ts, and pnpm build produces a dist directory for static hosting; a live demo runs at citrusgrid.pages.dev.

What makes CitrusGrid stand out?

• Three-language i18n — ships Chinese, English and Japanese interface strings, with translated READMEs at docs/README.en.md and docs/README.ja.md.
• Markdown pipeline — GFM syntax and KaTeX math formulas render from plain Markdown post files.
• Build-time search — pnpm build runs Pagefind to generate a local full-text search index, so no search service is needed.
• Pluggable comments — adapters currently target utterances, and a documented interface at src/comments/使用规则.md lets you substitute another comment system.
• Pluggable analytics — a bundled visitor-stats plugin with reserved global and per-post PV/UV interfaces; the visitor-stats service must be deployed yourself on a Cloudflare Worker.
• Table of contents — a sticky desktop sidebar plus a mobile modal version.
• Dark and light themes — the README documents both modes with matching home page and article screenshots.
• Code and image handling — Prism highlighting runs at build time with copy buttons and zero client-side JavaScript, alongside a PhotoSwipe lightbox and LQIP gradient placeholder skeletons, plus RSS output and a friend-links page.

Who should use CitrusGrid?

• Markdown-first personal bloggers who want to write plain .md files and get a styled blog without touching HTML.
• Developers optimizing Core Web Vitals who want build-time highlighting, preloaded modules and no runtime framework JavaScript in articles.
• Multilingual writers publishing in Chinese, English or Japanese from one codebase.
• Astro or TypeScript developers who prefer a single site.config.ts for configuration and Biome for formatting and linting.

What can you do with CitrusGrid?

• Scaffold and write posts: run pnpm new-post [slug] to generate a post template, then fill in frontmatter fields such as title, slug, index, description, category, tags, published, updated and draft.
• Pin and order content: set the index field to a positive integer to pin a post, with larger numbers ranking higher; 0 leaves it unpinned.
• Ship to a static host: run pnpm build, then upload the dist output to any platform; pnpm preview checks the built site locally.
• Extend the site: swap in a custom comment or stats plugin through the documented interfaces in src/comments/ and src/stats/.

How does CitrusGrid work?

1. Clone the repository and install dependencies with pnpm install (a preinstall hook runs only-allow pnpm, so npm and yarn are rejected).
2. Edit src/site.config.ts to set blog options, and optionally disable automatic updated timestamps written from file modification times.
3. Run pnpm dev and open http://localhost:4321.
4. Run pnpm build for production, which injects modulepreload, minifies inline scripts and generates the Pagefind search index.

Supporting commands include pnpm check (astro check), pnpm type-check (tsc over src and scripts), pnpm format-post-meta to reorder frontmatter fields, and pnpm format, pnpm format:all and pnpm lint for Biome.

Pricing

CitrusGrid is free and open source under the MIT License, with terms in the repository's LICENSE.txt file.

Alternatives

Astro Paper.

FAQ

Is CitrusGrid free?

Yes. CitrusGrid is released under the MIT License, so you can use, modify and self-host it without paying for tiers or seats. There is no hosted paid plan; you deploy the built dist folder to your own static host.

What does CitrusGrid require to run?

You need Node.js 22.14.0 or newer and Astro 7.2.9 or newer. Dependency installation is locked to pnpm, enforced by a preinstall script running only-allow pnpm, so npm and yarn installs will be blocked.

Does CitrusGrid include comments and visitor statistics?

Comments are pluggable with a current utterances adapter. Statistics are only partly built in: the visitor-stats plugin requires you to deploy the companion service on a Cloudflare Worker yourself, and the reading-statistics interface is reserved rather than active.

Which languages does CitrusGrid support?

CitrusGrid ships Chinese, English and Japanese localization for the interface, with README translations in docs/README.en.md and docs/README.ja.md. Content itself is written in Markdown, so posts can be authored in any language.

What frontmatter fields does a CitrusGrid post need?

Required fields are title, slug, index, description, category, tags and published. The optional updated field is written automatically at dev and build time from the file modification time unless you turn that off in src/site.config.ts, and draft marks unpublished posts.