reef

KO | EN

gitlite — search

#java #mysql #http #javascript #csharp #web #devops #cross-platform #typescript #awesome

(★ 9)

Reef, a free bilingual Astro 7 blog theme by Aloha Pixel. Light by default with a composed dark mode, English and French, RSS per language. Demo: https://reef.alohapixel.app

File Explorer

ZIP Download

- settings.json
- - verifier.yml
- - astro.md
  - motion.md
  - seo.md
  - tailwind.md
  - typescript.md
- design.md
- - about.png
  - blog.png
  - contact.png
  - default.png
  - topics.png
- reef-iphone-poster.webp
- app.mjs
- checks.mjs
- covers.mjs
- favicon.mjs
- house.mjs
- og.mjs
- poster.mjs
- rebrand.mjs
- verify.lisibilite.mjs
- verify.mjs
- verify.probe.mjs
- - legalData.json.ts
  - navData.json.ts
  - siteData.json.ts
  - siteSettings.json.ts
- - config.ts
  - content.ts
  - index.ts
- - haptics.ts
  - pagination.selfcheck.ts
  - pagination.ts
  - posts.ts
  - schema.selfcheck.ts
  - schema.ts
  - spring.ts
  - textUtils.ts
- - BaseHead.astro
  - BaseLayout.astro
- - 404.astro
  - llms.txt.ts
  - robots.txt.ts
- - global.css
  - prose.css
  - tokens.css
- content.config.ts
- worker.ts
- - content.md
  - fluidity.md
  - i18n.md
  - mobile-app.md
  - motion.md
  - seo.md
  - tokens.md
  - ui-primitives.md
- index.md
- log.md
- overview.md
.gitignore
AGENTS.md
astro.config.mjs
capacitor.config.ts
CHANGELOG.md
CLAUDE.md
DEPLOY.md
LICENSE
NOTICE.md
package.json
PHOTOS.md
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
SPEC.md
THIRD-PARTY.md
tsconfig.json
wrangler.toml

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A free, bilingual blog theme for Astro 7, light by default. 
 Reading-first typography, MDX collections, art-directed light and dark modes, 
 owned SEO, and an iOS / Android build from the same source.

<a href="https://reef.alohapixel.app">Live demo</a>
 &nbsp;·&nbsp;
 <a href="https://reef.alohapixel.app/fr/">Version française</a>
 &nbsp;·&nbsp;
 <a href="#quick-start">Quick start</a>
 &nbsp;·&nbsp;
 <a href="https://alohapixel.app/themes/">The rest of the family</a>

---

A blog theme for Astro 7, by Aloha Pixel. One repository gives you the whole
front of a writing publication: a home that leads with the latest piece, a
paginated blog, topic and author pages, a reading column with a table of
contents, and a per-language RSS feed. In English and in French, from the same
source.

The demo publication is Reef Notes, a fictional three-person web studio's
notebook: build logs, type specimens, and the unglamorous half of freelancing.
Every word lives in a typed dictionary or in a Markdown post, never inside a
component.

Reef is built to be read. You get clean, commented, strictly typed source
with a maintained wiki and agent tooling, not a black box.

## What is in the box, counted from this repo

Numbers below were counted from the source, not estimated (snapshot
2026-08-30; `pnpm build` green, `pnpm check` clean).

| What | Count |
|---|---|
| Pages emitted by `pnpm build` | 55 |
| Plain-text endpoints | robots.txt, llms.txt, per-language rss.xml, sitemap-index.xml |
| Content collections (zod validated) | 3 (posts, authors, topics) |
| Demo content entries | 9 posts, 3 authors, 5 topics, in 2 languages |
| UI primitive families (src/components/ui) | 36, across 63 .astro files |
| Primitive files that need a script tag | 10 of 63; the rest are pure HTML and CSS |
| Section components | 24 |
| Original hand-drawn icons | 60 |
| animate-* utilities (motion catalog + brand tokens) | 55 + 3 |
| Languages, from one page source each | 2 (English at the root, French under /fr/) |
| Runtime dependencies | 9, every one listed in THIRD-PARTY.md |

## Why it feels expensive

- **Almost no JavaScript.** Dialogs are native `<dialog>`, accordions are
 native `<details>`, the marquee is pure CSS. The scripts that ship are the
 mobile drawer, the theme switch, the shrinking navbar and the reader's table
 of contents, and all of them survive view transitions.
- **A design system, not a stylesheet.** One file (src/styles/tokens.css)
 defines the palette, semantic roles and generated utilities. Markup only
 speaks roles (bg-primary, bg-card, text-muted-foreground), so
 `pnpm rebrand "#yourhex"` repaints the theme, the favicon and the share
 cards from a single colour.
- **An owned SEO layer.** Canonical, Open Graph, JSON-LD builders, robots.txt,
 llms.txt, a per-language RSS feed and the sitemap are hand-written, readable
 files in the repo, not a plugin.
- **Two themes, not one switch.** Semantic tokens invert under one `.dark`
 class, applied before first paint, with zero flash. Light and dark do not
 share a shadow recipe: dark swaps cast shadows for luminous borders.
- **Bilingual by construction.** One page source per route, one output per
 language, one post file per language under the same slug. The dictionary is
 a typed object, so a missing French key is a build error, not a silently
 English sentence in production.
- **Accessibility as a feature.** 44px touch targets, correct aria wiring,
 visible focus everywhere, and reduced motion honored at both the CSS and the
 scroll-timeline layer.

## Stack

Astro 7 (static output, no adapter), Tailwind CSS 4 (CSS-first, no config
file), tailwind-variants, @astrojs/mdx (Markdown and MDX posts) and
@astrojs/sitemap, self-hosted fonts via Fontsource (Space Grotesk, Instrument
Sans, both OFL); the accent word of a heading keeps the heading font under a
turquoise wave underline, so no third font loads. Node >= 22.18 and pnpm. No
React, no animation library, no WebGL.

## Quick start

```bash
pnpm install
pnpm dev        # http://localhost:4321
```

`pnpm dev` fetches the demo photographs into `src/assets/` before the server
starts, because the repository does not version them.

All commands:

```bash
pnpm dev          # dev server
pnpm build        # static site into dist/
pnpm preview      # serve the build locally
pnpm check        # astro check (types and templates)
pnpm rebrand "#7a59ff"   # repaint the theme from one brand color
pnpm rebrand --restore   # back to the Reef palette
pnpm og           # regenerate the Open Graph cards in public/og/
pnpm app          # build tuned for a native Capacitor shell

node src/js/schema.selfcheck.ts
node src/js/pagination.selfcheck.ts
```

## Structure

```text
src/
 components/
 ui/ 36 primitive families (button, dialog, tabs, reveal, ...)
 Sections/ 24 sections, grouped by page (Home/, Post/, Archive/, Search/, Global/, Legal/)
 svg/icons/ the 60-icon original set
 config/ typed site data: siteData, navData, legalData
 content.config.ts the posts, authors and topics collections, zod schemas
 data/ your content: posts (Markdown/MDX), authors and topics (JSON)
 i18n/ the bilingual layer: config, helpers, en/ and fr/ dictionaries
 js/ pure logic: JSON-LD builders, pagination, text utils
 layouts/ BaseLayout + BaseHead (the entire <head>, hand-written)
 pages/ [...locale]/ (index, blog, topics, authors, about, contact, legal), 404, robots, llms, rss
 styles/ tokens.css, global.css, prose.css, the motion catalog
scripts/ rebrand.mjs, og.mjs, app.mjs
wiki/ how the theme works, anchored to the code
docs/ the five convention files, one per subsystem
```

## Make it yours, in order

1. **src/config/siteData.json.ts**: name, title, description, author. This is
   the only file you must edit to change the publication identity.
2. **astro.config.mjs**: set `site` to your production URL. It feeds canonical
   URLs, OG tags, the sitemap, robots.txt, llms.txt and the RSS feed at once.
3. `pnpm rebrand "#yourbrandcolor"`, then `pnpm og` to repaint the share cards.
4. **src/data/**: replace the demo posts, authors and topics. One Markdown post
   per language under the same slug.
5. **src/i18n/ui/en/** and **src/i18n/ui/fr/**: all the interface copy. Nothing
   displayed lives in a component.
6. **src/config/navData.json.ts** and **legalData.json.ts**: your links, and the
   privacy and terms copy. The bracketed fields to fill in are not there: they
   are in the legal notice, in src/i18n/ui/en/pages.ts and src/i18n/ui/fr/pages.ts.

## Before you deploy

- [ ] `site` in astro.config.mjs points at your real domain.
- [ ] `demoNotice` in src/config/siteData.json.ts is emptied, so the footer
      line saying "this site is a demo of the Reef theme" does not render on
      your site. The demo keeps it; you clear the field, and there is no
      component to open.
- [ ] `pnpm og` ran after your rebrand, so the cards in public/og/ carry your
      colors and not Reef Notes'.
- [ ] Legal copy in src/config/legalData.json.ts reviewed by a human who may
      legally have an opinion, and the bracketed fields of the legal notice
      (src/i18n/ui/en/pages.ts and src/i18n/ui/fr/pages.ts) filled in. It all
      ships as a generic starting point, in both languages, and none of it is
      legal advice.
- [ ] The demo posts, authors and topics replaced with your own.
- [ ] The contact form points at your own endpoint, or is removed. It ships
      with no `action` on purpose (the note is at the top of contact.astro).
- [ ] `pnpm check` and `pnpm build` are green, and the selfchecks pass.

Deploy dist/ to any static host: Cloudflare Pages, Netlify, Vercel, an nginx
box. No adapter, no server, no environment variable required.

## Ship it as a native app (Capacitor)

Reef builds to plain static files with no server, no external CDN and local
fonts, which is exactly what Capacitor wraps. Every fixed element respects
`env(safe-area-inset-*)`, viewport heights use `svh` and never `vh`, touch
targets are 44px, and no page overflows horizontally at 390x844.

```bash
pnpm app          # build tuned for a native shell
npx cap add ios
npx cap sync
npx cap open ios
```

`capacitor.config.ts` ships with the theme. The full guide, including the
checklist Apple reviewers care about, is in
[wiki/subsystems/mobile-app.md](wiki/subsystems/mobile-app.md).

## Documentation

- AGENTS.md: the operating manual (conventions, commands, gotchas), binding
  for humans and agents alike.
- docs/conventions/: the five convention files (astro, tailwind, typescript,
  motion, seo), each anchored to real files in this repo. They are written to
  be read by a human on day one and by any coding assistant afterwards.
- wiki/: start at wiki/overview.md; each subsystem has its own anchored page.
- THIRD-PARTY.md: the complete honest inventory (two OFL fonts, permissive
  npm packages, and the photographs that ship with the demo).

## Questions

Issues are turned off on this repository, and that is deliberate: support for
this theme is handled in one place rather than two.

- Something is wrong with the theme, or you want to tell us it helped:
  https://alohapixel.app/contact/
- The rest of the family:
  https://alohapixel.app/themes/

Pull requests are welcome all the same.

## What the paid themes add

Reef ships the whole foundation: the UI primitives, the typed bilingual layer
with its language switcher, the measured dark mode, the owned SEO, the motion,
the verification scripts and the conventions written for agents. That is
deliberate: it is how you try the house without paying, and for a blog it is
complete.

The six paid themes add the business built on top of that foundation: a shop
with products and a cart, an eight-screen back office, a headless storefront
read from WooCommerce or Shopify, a SaaS site with its pricing page and its
eight-screen dashboard, a launch page with its pricing section. Not one of
those files is in Reef.

The seven themes, side by side, with prices and live demos:
https://alohapixel.app/themes/

## License

MIT, full text in [LICENSE](LICENSE), which holds the MIT text and nothing else
so that GitHub reads it correctly. Use it, fork it, sell what you build with it,
no attribution required. Republishing Reef itself as your own theme is what the
MIT license already allows, so there is nothing to negotiate here.

The photographs are covered separately, and [NOTICE.md](NOTICE.md) says so in
full: the ten photographs in src/assets/ come from Pexels and carry the Pexels
licence, which is free for commercial and personal use, requires no attribution
and allows redistribution. Keep them in the site you publish with Reef, or
replace them with your own; both are inside the licence. scripts/covers.mjs is a
plain list of URLs, and a post with no cover falls back to a typographic card.
PHOTOS.md names the Pexels page of every single file.

NOTICE.md carries the rest of what the MIT grant does and does not reach: the
photographs, the demo content, and the fonts and npm packages inventoried in
THIRD-PARTY.md. Nothing there restricts the MIT grant.

Provided as is, without warranty.

reef

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README