Gloss

Gloss is a free, MIT-licensed Astro theme for a personal blog of long essays, built around footnotes that render as handwritten margin notes beside the paragraph that mentions them. Written by ondelva, it targets static output and is styled with Tailwind CSS v4.

What is Gloss?

Gloss is an Astro 7 theme for a personal blog of long essays. Authors write posts in Markdown or MDX and use ordinary Markdown footnote syntax ([^1]); the theme moves each note into a wide right margin, set in handwriting, next to the paragraph that references it. The build produces a static site, and the only client-side JavaScript is the theme toggle and the margin-note spacing logic.

What makes Gloss stand out?

• Margin footnotes — Standard [^1] footnotes are relocated beside their paragraph; on small screens they sit under the paragraph with a pencil rule, and long notes switch to small print.
• Hand marks in Markdown — ==highlight== and ++pencil underline++ render a highlighter stroke and pencil underline, usable in posts and the home page's opening line.
• Framework and styling — Astro 7 with Tailwind CSS v4, static output, type-safe content collections for Markdown and MDX.
• Included pages — Home with an opening line and handwritten note, post pages, an archive by year, an About page with margin notes, and a 404.
• Publishing extras — Word counts and reading times, RSS, sitemap, and structured data.
• Performance and reach — Dark mode, responsive from 360px, Lighthouse 95+ across all four categories, checked in CI.
• Authoring aids — AGENTS.md for Claude Code / Cursor, plus a dev-only /styleguide route showing every colour token, type size, and a sample essay with margin notes.
• Configuration — Site name, URL, opening line and switches live in src/config.ts; colours are tokens overridden in src/styles/theme.css.

Who is it for?

• Essayists and personal bloggers: publish long-form writing with numbered margin notes and hand marks without touching layout code.
• Writers migrating off Medium or Substack-style platforms: keep footnote-based annotation on a static site they host themselves.
• Astro developers: start from a typed content collection, token-based theming, and a documented config file rather than a blank layout.

What can you do with Gloss?

• Run an essay archive: posts automatically appear in a year-by-year archive, with reading times and RSS for subscribers.
• Annotate as you write: add a footnote or a highlight inline in Markdown and get a hand-drawn-style mark or margin note with no extra markup components.
• Deploy statically: one-click deploy buttons are provided for Cloudflare, Vercel and Netlify, plus GitHub Pages support; set SITE_URL afterwards.

How does Gloss work?

Install Node.js 22.12+ and pnpm 9 or newer, run pnpm create astro@latest my-site -- --template ondelva/astro-theme-gloss, then pnpm install and pnpm dev. Everything site-specific is edited in src/config.ts, and documentation covers content, customization and deployment.

Pricing

The free edition is MIT-licensed. A Pro edition at $49 for one person or $129 for a team of up to ten adds topics, a reading log, Pagefind search including margin notes, series, Buttondown subscribe forms, Giscus comments, per-post share cards, additional hand-mark components, four colour presets instead of one, a second font pairing, and email support within two business days.

FAQ

Is Gloss free?

Yes. The free edition is MIT-licensed and includes the margin-note system, highlight and pencil underline marks, the home page, archive, About page, RSS, sitemap, dark mode and a removable one-line footer credit.

What is not in the free edition?

The free version has no search, no series grouping, no subscribe form, no comments and no topics or reading-log pages. It ships one colour preset, one font pairing, and a single default share image instead of per-post cards.

Does it work without JavaScript?

Almost entirely. The only client-side JavaScript is the theme toggle and the margin-note spacing, and all pages are statically generated at build time.