Mailer

Mailer is a free, MIT-licensed Astro theme for publishing a newsletter with a public archive, where issues are numbered and the archive reads as a structured index rather than a grid of cards.

What is Mailer?

Mailer is a static-site newsletter theme built on Astro 7, Tailwind CSS 4 via the Vite plugin, Vite 8, and TypeScript. It takes numbered issues written in Markdown or MDX — validated by Astro content collections — and produces a full publication site: a front page assembled from the archive, a year-grouped archive index, per-issue pages, topic and writer pages, a client-side search page, and RSS. The project is published by xocoweb and previews live at mailer.xocoweb.workers.dev.

What makes Mailer stand out?

• Schema-validated issues — each issue's frontmatter is checked by the collection schema for issue number, title, excerpt, topic, date, writer, cover with alt text and photo credit, plus featured and draft flags; a missing excerpt or unknown topic fails the build.
• No-repeat front page — the latest issue leads at full width, the next two become cards, and the rest fall into a numbered index, with every block hiding itself when empty.
• MDX body blocks — six blocks need no import: callouts in six tones, toggles, bookmark cards that pull Open Graph tags from the linked page at build time, an audio card, a file download, and a captioned figure with an optional wide break-out.
• Runtime lightbox — arrow keys, swipe, a counter and preloaded neighbours, applied at runtime so plain Markdown images get it too.
• Provider-neutral signup — the form posts to any endpoint (Buttondown, Kit, Mailchimp, Listmonk, a custom handler) and renders disabled until configured.
• Static client-side search — a generated JSON index powers a header dialog on Ctrl/Cmd K and a results page whose query lives in the URL, with no external service or API key.
• Config-driven identity — site settings live in src/config/site.ts, topics in src/config/topics.ts, and writers in src/config/writers.ts, so the publication can be renamed without touching components.
• SEO and feeds built in — canonical URLs, sitemap, robots.txt, Open Graph and Twitter/X cards, JSON-LD (BlogPosting with word count and read time, BreadcrumbList, WebSite with search action), share cards cropped from covers at build time, and an /rss.xml feed carrying full issue content.

Who is it for?

• Independent newsletter writers: publish numbered issues with a public archive that stays legible as it grows.
• Small editorial teams: manage several writers through the writers config, with bios and portraits keyed by author name.
• Publishers moving off a hosted newsletter platform: collect signups through any POST endpoint while owning the archive, search and RSS.

What can you do with Mailer?

• Launch a publication site: rename identity, topics and writers in three config files, then add issues as folders containing an index.md or index.mdx and a cover image.
• Ship rich issue bodies from MDX: use callouts, toggles, bookmarks, audio, downloads and figures without importing components.
• Add search without a service: a build-time JSON index feeds both the keyboard dialog and the results page at no cost and with no API key.

How does Mailer work?

Run npm install and npm run dev locally (Node.js 22.12.0 or newer); npm run build produces the static output and npm run preview serves it. Issues live in src/content/issues, and the bundled demo images — Pexels gradients and Unsplash writer portraits — should be replaced with your own before publishing.

Pricing

Mailer is free under the MIT license, for both personal and commercial projects; support is limited to GitHub issues for bug reports and questions, with custom design and feature work excluded.