Popular: an Astro theme for meetups & communities

Built to make your community seen and famous.

AI agents / automated contributors: read AGENTS.md before making changes. It covers the repo layout, build commands, the Hugo-Astro parity contract, and content conventions.

Something not working as described? Please open an issue as you hit it, while it's fresh: a command that errors, a step that's out of date, a sentence you had to read three times. Setup friction is a bug. Reporting it here gets it fixed upstream, so the next person doesn't hit the same wall. Fixes to the wording are welcome as pull requests too.

Popular is a warm, community-first Astro theme for meetups, user groups and small events. Named after the song Pop!ular by Darren Hayes, it is the Astro twin of hugo-theme-popular. Both share the same design tokens, CSS, behaviour JS and content model; see PARITY.md for the cross-repo contract.

• Composable home page (hero, stats, features, auto next-event, latest posts, organizers, testimonials, CTA)
• Blog with tag filtering, tag pages, RSS, and per-post speaker bios
• Events that split into upcoming and past automatically, with speaker profiles, venue pages (address, buzz-code arrival notes, accessibility) and check-in instructions
• Organizers / team page
• Docs (handbook & runbooks) with scroll-spy TOC and checklists that remember progress
• Dark footer with land-acknowledgement slot and social links
• Alt text, required: CI builds every site and fails if any image lacks alt text
• One-command imports: populate events, speakers and venues from Sessionize or a spreadsheet (scripts/), cross-referenced and dependency-free
• Agent & human friendly: ships AGENTS.md so AI coding agents follow the same rules as human contributors
• Translatable UI: every template string lives in one place (Hugo i18n/, Astro STRINGS config), so a site can run in any language
• Re-brand the whole theme from src/config.ts, no CSS edits needed

Full documentation lives on the theme's project site (deployed from the Hugo repo): start at /docs/quick-start/?fw=astro. This README covers the essentials.

Multi-author blogging: posts support authors: ["slug"] (profiles in src/content/authors/ with bio, photo, socials, website → linked profile pages) and inline guestAuthors for one-off guest writers, plus a plain author string fallback.

Start a site with the scaffolder. You get a small project that depends on the theme, so updating is npm update astro-theme-popular rather than diffing tags and re-copying files:

npm create popular-site@latest my-community
cd my-community
npm install
npm run dev          # http://localhost:4321

Pick the neutral "Your Community" starter (the default) or any of the four fictional demos as a fuller example to edit down: Rocky Cove Aquarium Club (teal), Lucky Town Foodie Club (copper), KDrama Fan Club (indigo) and Truly Madly Riley (gold, a personal site for one fictional superfan). All communities and venues in them are made up for demonstration.

Live: the starter is the deployment root, and the demo gallery links the other four.

Each demo is its own workspace consuming the package, so there is no activation step: build or serve one where it lives.

npm install                              # one install for every workspace member
npm run dev --workspace demos/aquarium   # or: npm run demo:aquarium
npm run build --workspaces               # build everything

DEMO_BAR in a demo's popular.config.ts drives the in-page switcher; it is null on the starter and on anything the scaffolder writes, so it never appears on a real site.

Front-matter schemas live in src/content.config.ts (zod-validated) and are kept 1:1 compatible with the Hugo theme, so content moves between the two freely.

import Callout from '../../components/Callout.astro';
import Checklist from '../../components/Checklist.astro';

<Callout tone="tip" title="Two-deep rule">
  Aim for **two** organizers at every event.
</Callout>

<Checklist id="rb-venue" items={[
  'Shortlist 2–3 venues',
  'Confirm step-free access',
]} />

Checklist progress persists in the visitor's browser (localStorage), using the same key format as the Hugo theme.

• scripts/sessionize-import.py: populate src/content/events/ and src/content/speakers/ from a Sessionize event's public "API / Embeds" endpoint:

  python3 scripts/sessionize-import.py --url https://sessionize.com/api/v2/<embed-id>/view/All --site .

  Existing files are never overwritten, so edit freely after importing.

• scripts/spreadsheet-import.py: the same import from one spreadsheet with tabs for Speakers, Venues, Organizers and Events (dependency-free .xlsx or per-tab CSVs). --make-sample community.xlsx writes a starter workbook (one ships at scripts/sample-community.xlsx); import it with --xlsx community.xlsx --site ..

The helper scripts have a dependency-free test suite: python3 -m unittest discover -s scripts/tests (also run in CI).

Static output: deploy dist/ to Netlify, GitHub Pages, Cloudflare Pages, etc. Set site in astro.config.mjs for correct RSS/OG URLs.

Serving from a subpath (a GitHub project page lives at user.github.io/repo/) is supported: set site and base in astro.config.mjs, and every link, image and feed URL picks it up. Your config and content need no changes, paths keep their leading slash.

export default defineConfig({
  site: 'https://you.github.io',
  base: '/my-community',
  integrations: [mdx(), sitemap(), popularMarkdown()],
});

scripts/setup.py writes both from your base_url answer, along with a ready-to-run GitHub Pages workflow at .github/workflows/deploy.yml (only when the site has no workflows of its own). If you write your own components or pages, wrap the URLs you emit: import { withBase } from './lib/url' (npm consumers: from 'astro-theme-popular/url'), then href={withBase('/about/')}.

Popular is free and MIT licensed. If it made your community site easier, there are three ways to support the work:

• Star the repo so other organizers can find it
• Tell others about it: share it with another meetup, club or community, or use it yourself for your next community site
• Sponsor on GitHub

Typography: Inter & Quantico (Google Fonts). Icons: Font Awesome 6. MIT: see LICENSE. Fork it, adapt it, and share your community's version.

Releases are tagged v0.x (semver, in lockstep with hugo-theme-popular); the 1.0 release will mark the content model and brand keys as stable. Changes are documented in CHANGELOG.md. To hear about updates, watch this repo (Watch → Custom → Releases) or subscribe to the releases feed. Since Astro sites vendor the theme (you copy this repo), updating means re-copying the files you haven't customized; the changelog tells you which areas moved, and the full guide is at /docs/updating/.

Releases are cut by the Release workflow after the CHANGELOG entry is merged: gh workflow run release.yml -f version=X.Y.Z, run in both repos. It validates the CHANGELOG section and cross-repo parity, then tags vX.Y.Z and publishes the GitHub Release with that section as the notes. On this repo it also checks that package.json matches the version.