Grimorio

Grimorio is an Astro blog theme for guides, notes, essays, and dev logs, with English and Spanish included out of the box and social images generated at build time.

What is Grimorio?

Grimorio is a static blog theme built on Astro 7 with Vue 3 used only for interactive islands and styled with Tailwind CSS 4. It takes Markdown posts authored in src/content/posts/en/ and src/content/posts/es/ as input and outputs a static site with per-language routing, generated social cards, RSS feeds, and a sitemap. It is based on Kanade-Astro by sudoriaa and is released under the MIT license.

What makes Grimorio stand out?

• Bilingual by default — English is served at / and Spanish at /es/, with a language switch that keeps visitors on the same page; posts are paired across languages by matching file names.
• Generated images — each post gets a 1200×630 social card and a wide hero banner rendered at build time from its title and category using Satori and Sharp; dropping an image into src/assets/banners/ overrides the banner for a specific post.
• Client-side full-text search — search runs over every post and opens with Ctrl or ⌘ + K.
• SEO included — per-page canonical URLs, hreflang, Open Graph and Twitter tags, JSON-LD structured data, a sitemap with real lastmod dates, per-language RSS, robots.txt, and an llms.txt summary for AI crawlers.
• Theming — light and dark modes respect the system preference and prefers-reduced-motion, with no flash on load.
• Content structure — Markdown posts with categories, tags, a monthly archive, and pagination; rendered fenced code has syntax highlighting and a copy button.
• Performance — static output, inlined critical CSS, hover prefetching, and self-hosted fonts; the README reports a 100 Lighthouse score and a Playwright suite covering navigation, search, theming, i18n, and metadata on desktop and mobile.

Who is it for?

• Bilingual writers publishing essays or notes in both English and Spanish who want paired posts without maintaining two sites.
• Developers keeping a dev log who want Markdown posts, tags, and an archive without building a site from scratch.
• Astro users who want a starting point with i18n, search, and generated social images already wired up.

What can you do with Grimorio?

• Personal bloggers: write Markdown posts with categories, tags, and featured flags, and get a social card per post without design work.
• Spanish-language publishers: swap the default language to Spanish or drop to a single language by editing languages and defaultLanguage in src/i18n/index.ts.
• Theme contributors: fork it, replace the example posts and favicons, set the production domain, and deploy to Cloudflare Pages, Netlify, Vercel, or GitHub Pages.

How does Grimorio work?

Install with pnpm (Node.js 24 required, 22.12 minimum), run pnpm dev to open the site at localhost:4321, and pnpm build to type-check and build into dist/. Customization centers on src/site.config.json for site name, author, and nav, src/i18n/*.json for interface text, and src/styles/global.css for theme colors.

FAQ

Is Grimorio free?

Yes. Grimorio is released under the MIT license, so you can use, modify, and redistribute it, keeping the LICENSE file in the repository.

Does Grimorio support more than two languages?

Languages are declared in src/i18n/index.ts via the languages array and defaultLanguage. You can add or drop entries, but you must keep the sitemap locales in astro.config.mjs in sync.

Can a post use its own banner image?

Yes. Posts receive a generated hero banner from their title and category, and placing an image in src/assets/banners/ overrides the banner for that specific post.

Where does Grimorio deploy?

The build is fully static, so any host serving a folder works. The README documents Cloudflare Pages with pnpm build and a dist output directory, plus a SITE_URL environment variable for correct metadata.