Home on Popular

Mariatta

Mon, 01 Jan 0001 00:00:00 +0000

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

1 · Get the theme

Add the theme to your Hugo site as a git submodule (or copy the folder into themes/popular; Hugo Modules users can instead import github.com/Mariatta/hugo-theme-popular, see the README):

Configuration reference

Mon, 01 Jan 0001 00:00:00 +0000

Site identity

title, tagline, description, brandName + brandSub (the two-line wordmark in the header), logo, ogImage, and landAcknowledgement (footer slot, leave empty to hide).

Content model

Mon, 01 Jan 0001 00:00:00 +0000

Blog posts

title, date, description, image, tags[], plus authorship (see below) and an optional speaker block (name, title, photo, bio) for recap posts.

Theming

Mon, 01 Jan 0001 00:00:00 +0000

The one-block re-brand

Every colour, font and radius in the theme resolves through CSS custom properties (design tokens). The brand config block overrides the important ones at render time:

Components & shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

Callout

Info, tip and warning boxes with an optional title.

Importing content

Mon, 01 Jan 0001 00:00:00 +0000

Both importers ship in both repos (scripts/ directory), work for either framework (the output format is auto-detected from your site), and follow the same safety rules:

Updating the theme

Mon, 01 Jan 0001 00:00:00 +0000

Hearing about releases

Popular is released with semver tags (v0.2.0), in lockstep across the Hugo and Astro repos: one version number covers both. Three ways to hear about a new one:

Watch the repo: on GitHub, Watch → Custom → Releases. You get a notification per release, nothing else.
RSS: subscribe to the releases feed in any feed reader.
The changelog: CHANGELOG.md ships in both repos and is the same file in each.

Before you update

Read the release notes (or the changelog section, same text). During 0.x, a minor version may contain breaking changes; when one does, the entry says so and tells you what to change. The 1.0 release will mark the content model and brand keys stable.

Demos & deployment

Mon, 01 Jan 0001 00:00:00 +0000

The four demos

All four are complete example sites, every page, guides, blog and events. They exist to prove one claim: the entire visual difference between them is one config block. None is more “official” than the others.

Migrating images from another theme

Mon, 01 Jan 0001 00:00:00 +0000

The short version

Popular references images at site-relative paths like /images/hero.png, and Hugo serves anything in your static/ directory at the site root. So the simplest migration is: put your images in static/images/ and reference them as /images/.... Nothing else to configure.

If your old theme kept images somewhere else (an assets pipeline, a page bundle, an img/ folder) and you’d rather not move them, you can mount that directory to /images/ instead.

SEO & structured data

Mon, 01 Jan 0001 00:00:00 +0000

What’s automatic

Every page gets a description, canonical URL, full Open Graph and Twitter card tags, og:locale, and a robots.txt advertising your sitemap. You don’t configure any of it.

The site also emits /llms.txt, a short plain-text summary for AI agents: what the community is, the next upcoming event (regenerated every build so it stays true), how to join, and links to the key pages and the calendar feed. On Astro it is always generated; on Hugo add LLMS to the home page’s outputs (the demos and starter already do).

FAQ sections

Mon, 01 Jan 0001 00:00:00 +0000

Why

First-timers have the same handful of questions: do I need experience, is it free, how do I find the room. Answer them where people land. The FAQ block also gives AI answer engines (ChatGPT, Perplexity, AI Overviews) clean question → answer text to quote.

Note: classic FAQ rich results are not a goal. Google restricts them to government and health sites, so don’t expect snippets. The value is on-page clarity and AI-friendliness.

Beyond meetups

Mon, 01 Jan 0001 00:00:00 +0000

The theme is a shape, not a topic

Everything in the theme maps to a general community pattern:

Events are anything scheduled: talks, watch parties, shifts, recording sessions, class meetings, gigs.
The blog is anything published on a cadence: recaps, news, release notes, episode notes, season announcements.
Organizers are the people behind it: hosts, teachers, crew, captains.
The docs area is the group’s operating knowledge: a handbook, runbooks, a code of conduct, house rules.

If your group has “things that happen”, “things you write down”, and “people who run it”, the theme fits, whatever you call yourselves. The section names themselves are renameable (hosts instead of organizers, and so on), so the vocabulary matches your group.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

One theme, two implementations: versions are tagged in lockstep in hugo-theme-popular and astro-theme-popular, and this file ships identically in both (PARITY.md Tier 1). Format follows Keep a Changelog; versions follow semver. During 0.x, minor versions may contain breaking changes; they will be called out here.

To hear about new releases: watch either repo on GitHub (Watch → Custom → Releases) or subscribe to the releases feed (https://github.com/Mariatta/hugo-theme-popular/releases.atom).

[Unreleased]

[0.7.0] - 2026-07-31

Changed

The footer shows the theme version (e.g. v0.7.0) next to the Popular credit, on the demos and the docs site.

Fixed

The “no upcoming events” empty state no longer renders on event-less sites such as the docs site; it appears only on a community that has an events section but nothing upcoming.

Added

Recaps toolkit: gallery + photo and pullquote shortcodes (Hugo) / Gallery + Photo and Pullquote components (Astro). The gallery is a CSS-grid figure list with no JavaScript and no lightbox (each photo links to its full-size image); alt is required and a missing one fails the build. A recap is a blog post tagged recap that uses both, with a worked example in the KDrama demo.
llms.txt: a build-time plain-text summary for AI agents at /llms.txt, naming the next upcoming event, how to join, and links to the key pages and the calendar feed. Always generated on Astro; on Hugo the site adds LLMS to its home outputs (the demos, exampleSite, and docs site do).
Docs: the deliberate non-features list (job board, member directory, comments, photo lightbox) and the stats strip as the social-proof pattern.

Added

Talk archive. Events gain optional recording / slides (single-talk meetups) and a talks[] array (title required; speaker, recording, slides optional); when talks[] is present it wins over the event-level fields. The event page renders a Talks section (or inline links for the simple case), and past-event rows show a recording cue. An opt-in /talks/ archive aggregates every talk newest-first, filterable by the parent event’s tags: enable it with content/talks/_index.md (Hugo) or SITE.talks = true (Astro). New UI strings watchRecording, viewSlides, hasRecording, talks, talksLead.

Changed

Speaker, organizer, and author profile pages no longer repeat the bio: the page hero is now a compact banner (eyebrow, name, back link) and the bio lives only in the persona card below it.

Added

Community chat bridge and speaker pipeline. params.community.chat = { url, label } adds a “Join the chat” CTA to the home hero, the footer, and the no-events empty state (platform-agnostic: Discord, Slack, Matrix, Zulip). The starter ships a “Start here” first-timer page (/start/) and a “Speak with us” call-for-speakers page (/speak/). params.speakers.invite = true appends a “Your name here?” card to the speakers list (new strings speakerInviteTitle, speakerInviteBody), off by default.

Fixed

Astro: the speakers and venues list pages (/speakers/, /venues/) were missing, so the “All speakers” / “All venues” back links on detail pages led to 404s. Both list pages now exist, mirroring the Hugo templates.

Added

Notice banner and designed empty states. params.notice = { text, url? } renders a static, non-dismissible banner above the header (inline-markdown text, an optional link, no JavaScript). When there are no upcoming events, the home page and the events list now render a designed empty state (a message, the community chat CTA if configured, and the calendar-subscribe link) instead of a blank section. New UI strings learnMore, joinChat.

Added

Venue access & logistics fields: wheelchair (a badge on the venue and on events held there), transit, parking, and a freeform access note, shown as a “Getting there & access” section. Inclusion as a data-model concern. Matching spreadsheet-importer columns. New UI strings gettingThere, wheelchairAccessible, transit, parking.

Added

Calendar feed: an iCalendar (.ics) feed of events at /events/calendar.ics, so members subscribe once and every future meetup appears in their calendar app. Reuses the event time parsing (so the feed and the Event structured data agree), marks cancelled events, and adds a “Subscribe to calendar” link to the events list. scripts/check-ics.py validates it in CI. Hugo: add Calendar to the events section outputs.

Fixed

Speaker, venue and organizer profile pages now show a back link to their list (matching blog posts and events); the organizer link follows the renamed team section. New UI strings allSpeakers, allVenues, allOrganizers.

Added

Astro package: component overrides. popular({ overrides: { Header: './src/overrides/Header.astro' } }) replaces any of Header, Footer, Hero, EventRow, PostCard, OrganizerCard, AuthorBox, PageHero without forking the theme. (Hugo adopters already override via native template lookup.)

[0.6.0] - 2026-07-23

Search-engine optimisation: structured data, crawl plumbing, Core Web Vitals, and an FAQ block. Zero client JavaScript added.

About Popular

Mon, 01 Jan 0001 00:00:00 +0000

Popular wasn’t designed in the abstract: it was built by a real-life serial conference organizer, distilled from years of running meetups, workshops and conferences. The ops handbook, the runbooks with checkboxes, the “venue wanted” badge: every feature comes from something a real community needed. It works for communities of any kind: tech meetups, supper clubs, aquarium keepers, fan clubs.

Who’s behind it

Popular is created and maintained by a multi-award-winning open source contributor and serial conference organizer. Open source isn’t a distribution channel here, it’s the root system: the theme is developed in the open, MIT licensed, and shaped by the same open source culture its creator has spent years building in.

Mariatta

Mon, 01 Jan 0001 00:00:00 +0000

Mariatta started Popular after one too many community sites rebuilt from scratch. She maintains both implementations.