Docs on Popular

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.