Reef

Reef is a free, bilingual blog theme for Astro 7 by Aloha Pixel that generates a static publication from Markdown and MDX content, with English and French outputs from the same source and an optional native iOS/Android build via Capacitor.

What is Reef?

Reef is a complete front-end for a writing publication built on Astro 7 with static output (no adapter). It takes Markdown and MDX posts, JSON author and topic files, and a typed i18n dictionary as input, and produces a 55-page static site that includes a home page, a paginated blog, topic and author pages, a reading column with table of contents, per-language RSS feeds, a sitemap, and plain-text endpoints like robots.txt and llms.txt. The demo publication, Reef Notes, is a fictional two-person web studio's notebook. The project is maintained by Aloha Pixel and ships under an MIT license.

Key Features

• Bilingual by construction — One page source yields English at the root and French under /fr/; the dictionary is a typed object so a missing French key fails the build instead of showing English in production.
• Almost no JavaScript — Dialogs use native <dialog>, accordions use <details>, and the marquee is pure CSS; only four scripts ship (mobile drawer, theme switch, shrinking navbar, and table of contents), all of which survive view transitions.
• Owned SEO layer — Canonical URLs, Open Graph tags, JSON-LD builders, robots.txt, llms.txt, per-language RSS, and the sitemap are hand-written files in the repo, not a plugin.
• Design system with one token file — src/styles/tokens.css defines palette, semantic roles, and generated utilities; markup uses roles like bg-primary and text-muted-foreground, so pnpm rebrand "#yourhex" repaints the theme, favicon, and share cards from a single color.
• Two themes, not one switch — Semantic tokens invert under one .dark class applied before first paint; dark mode swaps cast shadows for luminous borders instead of sharing the light shadow recipe.
• Typed content collections — Three zod-validated collections (posts, authors, topics) with 9 posts, 3 authors, and 5 topics in the demo, all validated at build time.
• Accessibility built in — 44px touch targets, aria wiring, visible focus everywhere, and reduced motion honored at both CSS and scroll-timeline layers.
• Native app-ready — Ships with capacitor.config.ts, a pnpm app build, safe-area insets, svh viewport heights, and no horizontal overflow at 390x844.

Who is Reef for?

• Bilingual writers and publishers who need to publish the same content in English and French without maintaining two separate sites.
• Independent developers and freelancers who want a clean, readable blog with a design system they can rebrand with one command.
• Design-savvy studios that need a publication-style site with topic and author pages, legal pages, and a contact form they can point at their own endpoint.
• Anyone targeting mobile app stores who wants to wrap their blog in Capacitor for a native iOS/Android app from the same codebase.

What can you do with Reef?

• Launch a bilingual blog: Write posts once per language under the same slug, and Reef outputs both / and /fr/ versions with per-language RSS feeds.
• Rebrand the entire site from one color: Run pnpm rebrand "#yourhex" to repaint tokens, favicon, and Open Graph cards.
• Ship a native app: Run pnpm app, then use npx cap add ios and npx cap open ios to build a Capacitor wrapper for the static files.
• Deploy to any static host: The dist/ folder works on Cloudflare Pages, Netlify, Vercel, or an nginx box without an adapter or environment variables.

How does Reef work?

The workflow is straightforward: install dependencies with pnpm, run pnpm dev for the development server, and place content in src/data. Posts live as Markdown or MDX under a slug that also maps to the French version. For production, pnpm build emits a static site into dist/, and pnpm check runs astro check plus TypeScript checks. The pnpm og command regenerates Open Graph cards, and pnpm rebrand --restore returns to the default Reef palette.

Pricing

Reef is free and open source under the MIT license. You can use it, fork it, and sell what you build with it without attribution. Republishing the theme itself is also permitted under the license. The only carve-out is that the photographs in src/assets are Aloha Pixel's own and are not part of the MIT grant; they must be swapped before publishing.

FAQ

Is Reef free?

Yes, Reef is free and MIT licensed. There is no paid tier, and the repo's README states the price as free. You can use it commercially and even sell what you build with it without attribution.

What versions of Astro and Tailwind does Reef use?

Reef uses Astro 7 with static output and Tailwind CSS 4 with a CSS-first configuration (no config file). It also uses tailwind-variants, @astrojs/mdx, and @astrojs/sitemap, with Node 22.12 or later and pnpm.

Does Reef support languages other than English and French?

Out of the box, Reef targets English and French from one source. The i18n dictionary is typed and the structure supports two languages; adding more languages would require extending that layer, which is not described in the README.

Can I build a mobile app with Reef?

Yes. Reef ships with Capacitor support: a capacitor.config.ts file, a pnpm app build tuned for a native shell, and a wiki guide covering the Apple review checklist. The static output works with no server, external CDN, or environment variable.

What do I need to replace before deploying?

The README's pre-deploy checklist includes setting site in astro.config.mjs, emptying the demoNotice string, running pnpm og after rebranding, reviewing legal copy, replacing demo posts/authors/topics, and pointing the contact form at your own endpoint. The demo photographs are not MIT-licensed and must be swapped.