Skip to content
Docs

Quick start

From zero to a running community site. Pick your framework once: the docs remember your choice.

New here? Start with Before you build: the handful of decisions (code of conduct, where the repo lives, how people RSVP) worth settling before you install. This page picks up once you’re ready to build.

Tell us when a step doesn't work

Please report problems with these instructions as you go, while the details are fresh: a command that errors, a step that’s out of date, a sentence you had to read three times, an assumption that didn’t hold on your machine. Setup friction is a bug in the docs, and reporting it is the only way it gets fixed upstream for the next person.

Open an issue on the repo you’re using, Hugo or Astro, with the step, what you ran, and what happened. Pull requests fixing the wording are just as welcome. If an AI agent is walking you through setup, ask it to write the report: it has the full transcript of what actually ran.

1 · Install 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):

hugo new site my-community && cd my-community
git init
git submodule add https://github.com/Mariatta/hugo-theme-popular.git themes/popular

Scaffold a site that depends on the theme, so updating it later is npm update astro-theme-popular rather than re-copying files:

npm create popular-site@latest my-community
cd my-community && npm install

It asks which starting point you want: the neutral starter, or any of the four demos as a fuller example to edit down.

Building a site with an AI agent?

Point your agent at this page plus the content model and let it drive. The brief it needs to use the theme:

  • Scaffold with step 1 above, then start from a demo (step 2), rather than building pages from scratch.
  • Interview, don’t hand-edit. The repo’s AGENTS.md has a “Setting up a new site for a user” protocol: the agent reads setup-questions.json, interviews you, and runs the setup wizard (step 3), which is the tested write path.
  • Content is Markdown with front matter under content/ (Hugo) or src/content/ (Astro); the fields are identical across both frameworks. See the content model.
  • Bulk content like events and speakers should be imported from Sessionize or a spreadsheet with one command, not typed by hand.
  • Preview with hugo server (Hugo) or npm run dev (Astro); both output a fully static site you can deploy anywhere.
  • Report what breaks. AGENTS.md tells the agent to flag any instruction here that is wrong, stale or fails when run, and to offer to file it upstream rather than quietly working around it. Take it up on that offer: it knows exactly which command failed.

Modifying or contributing to the theme itself is different work: point the agent at the repo’s AGENTS.md first (Hugo · Astro) for repo layout, parity rules, and the known gotchas. It doubles as the fastest human orientation.

2 · Start from an example

The fastest path is to copy one of the four demo sites (each ships as both a Hugo site and an Astro site) and make it yours: three fictional communities plus one personal site. All four are complete example sites, pick whichever vibe is closest.

# starter skeleton (neutral):
cp -r themes/popular/exampleSite/* .
# …or start from a full demo, e.g. the aquarium club:
cp -r themes/popular/demos/rocky-cove-aquarium/* .
hugo server

npm run dev               # boots the neutral starter skeleton
# …or activate a full demo first (copies its config + content into src/):
npm run demo:aquarium     # or demo:foodie / demo:kdrama / demo:superfan

When you’re ready, edit src/content/ and src/config.ts directly and delete demos/.

3 · Make it yours: run the setup wizard

The wizard turns the Before you build answers into config. It reads the same question schema, writes your config plus a code-of-conduct seed page, and leaves a DECISIONS.md recording what you chose (with handbook links) and what is still open.

It’s a single Python 3 script with no packages to install (Python 3 ships on macOS and most Linux; Windows users can get it from python.org). Prefer not to use it at all? Skip this step and edit the config by hand, everything the wizard writes, you can also set yourself.

python3 themes/popular/scripts/setup.py --dry-run  # interactive; Enter skips a question, shows the diff, writes nothing
python3 themes/popular/scripts/setup.py            # apply

It writes hugo.toml. Prefer to edit by hand? Everything lives under [params]; see the configuration reference.

python3 scripts/setup.py --dry-run  # interactive; Enter skips a question, shows the diff, writes nothing
python3 scripts/setup.py            # apply

It writes src/config.ts. Prefer to edit by hand? Everything lives in that one file; see the configuration reference.

On a fresh site started from an example (step 2) this just works: the wizard recognizes the unedited starter config and adopts it. Once you have hand-edited your config it won’t overwrite your work without --force, so preview with --dry-run first. Skip every question and you still get a clean starter config: the wizard is sugar, never a gate.

The one-file re-brand

Change brand.primary and the theme derives coherent tints for badges, tags and hovers automatically. Fonts, surfaces and radii are one line each. Details in Theming.

4 · Add your content

Blog posts, events, organizers and authors are plain Markdown files with front matter, the fields are identical in both frameworks. See the content model. Running your event on Sessionize, or planning in a spreadsheet? Import everything with one command instead of retyping it.

5 · Deploy

Both implementations output a fully static site. Deploy anywhere: GitHub Pages workflows are included in each repo. See Demos & deployment.

6 · Support the theme

Enjoying Popular? Star the repo so other organizers can find it, tell others about it (or use it for your next community site), and if it saves you real time, sponsor the work on GitHub.