Astro Keel

Astro Keel is a minimal, neutral, modern portfolio and blog theme built on Astro 7, designed to produce a fully static website with a single configurable accent color, dark mode, tags, RSS, and self-hosted fonts.

What is Astro Keel?

Astro Keel is a free, open-source (MIT-licensed) portfolio and blog theme for Astro 7, created by developer kpab. It takes Markdown and MDX content files as input and outputs a static site with dedicated works and blog collections, per-tag archive pages, an RSS feed at /rss.xml, and a sitemap. The theme is built with TypeScript, the Content Layer API, and MDX, and requires Node.js 22 or later. It can be scaffolded with the command npm create astro@latest -- --template kpab/astro-keel or by clicking "Use this template" on GitHub.

Key Features

• Portfolio + blog — Dedicated works and blog content collections with individual pages, plus per-tag archive pages at /blog/tags/[tag] and pagination every 10 posts.
• One-file site config — Site name, description, nav, footer, and locale all live in src/consts.ts; the accent color is a single CSS variable (--color-accent).
• Light + dark mode — Respects prefers-color-scheme and remembers manual toggles via localStorage, with no flash on load.
• Self-hosted fonts — Fraunces (display), Public Sans (body), and JetBrains Mono (code) loaded via @fontsource, with no external font CDN.
• i18n-ready — Typed UI dictionary under src/i18n/; setting SITE.locale to a BCP 47 tag switches the chrome, date formats, <html lang>, and RSS language. English and Japanese are included.
• Static search — Zero-backend full-text search at /search powered by Pagefind, indexed at build time.
• Auto OG images — Per-post and per-work Open Graph images rendered at build time with satori and sharp.
• Optional comments — Giscus comments on blog posts, opt-in via src/consts.ts, lazy-loaded and theme-synced; disabled builds ship zero Giscus bytes.
• RSS and SEO — RSS via @astrojs/rss, canonical URLs, Open Graph, Twitter cards, sitemap, and JSON-LD structured data (WebSite, BlogPosting, BreadcrumbList).
• Syntax highlighting — Shiki dual themes (light/dark) wired to the active color scheme.

Who is it for?

• Developers building a personal portfolio: they get a clean, editorial design with works and blog collections, auto-generated OG images, and a one-line accent color to match their brand.
• Bloggers who want a fast static site: the theme includes tags, pagination (10 posts per page), RSS, static search, and optional Giscus comments, all without a backend.
• Designers comfortable with Markdown: content authoring is just adding .md or .mdx files under src/content/; frontmatter supports hero images, tech lists, and draft status.
• Teams needing a multilingual site: with the built-in i18n dictionary system, adding a language is a small pull request; en and ja are already included.

What can you do with Astro Keel?

• Indie developers: showcase projects in a works collection with live links, source repos, and tech tags, then publish blog posts about them with optional comments.
• Technical writers: use the auto-generated table of contents on blog posts, Shiki syntax highlighting with dual themes, and static search to create a documentation-like blog.
• Designers: change the accent color in one line, swap fonts via CSS variables (--font-display, --font-body, --font-mono), and rely on fluid type and focus rings for accessible, responsive layouts.

How does Astro Keel work?

The theme is a GitHub template that scaffolds a new Astro project. After running npm install, developers add content as Markdown or MDX files in src/content/works/ and src/content/blog/. A config file (src/consts.ts) holds site identity, locale, nav, and footer; astro.config.mjs sets the site URL and base path. Running npm run build generates a static dist/ folder, with optional integrations like Pagefind search and satori OG images executed at build time.

FAQ

Is Astro Keel free?

Yes. The theme is released under the MIT License and free to use for personal or commercial projects. It is also listed on GitHub with a "Use this template" option.

What content types does it support?

It supports Markdown and MDX files in two content collections: works (portfolio entries) and blog (posts). Works frontmatter can include title, description, tech list, live link, repo link, thumbnail, order, and publish date. Blog frontmatter supports title, publish date, description, tags, draft status, and an optional hero image.

Does it require a backend for comments or search?

No. Comments use Giscus, which is backed by GitHub Discussions and is off by default. Search is powered by Pagefind, which indexes the static site at build time and runs entirely in the browser.

Which languages are supported for internationalization?

The theme ships with English and Japanese dictionaries. Setting SITE.locale to a BCP 47 tag switches all UI strings, date formats, html lang, og:locale, and the RSS language. Adding a new language requires copying a dictionary file and registering it in src/i18n/index.ts.

What are the Node.js and build requirements?

It requires Node.js 22 or higher. The build outputs a static site to ./dist, which can be deployed to any static host.