Skip to content

Add site search with Pagefind 1.6 (ranked results, show chips, dev auto-index) - #576

Draft
CGBassPlayer wants to merge 18 commits into
JupiterBroadcasting:developfrom
CGBassPlayer:pagefind-search
Draft

CGBassPlayer wants to merge 18 commits into
JupiterBroadcasting:developfrom
CGBassPlayer:pagefind-search

Conversation

@CGBassPlayer

@CGBassPlayer CGBassPlayer commented Jan 17, 2024 •

Copy link
Copy Markdown
Collaborator

Fixes #26

Depends on #1158 (Hugo 0.169.0 / Bulma 1.0.4). Merge that first.

Adds site-wide search at /search/, built on Pagefind 1.6.0, with a custom results UI that matches the site theme.

What it searches

Episodes (titles, descriptions, tags, show notes), shows, hosts and guests, picks and sponsors.

Ranking

Pagefind's own score is adjusted in search.js:

  • Title matches are promoted. A pick, sponsor, show or person whose title contains every query word goes to the top, in that order (linux unplugged → the show page, wes payne → the person page, 1password → the sponsor).
  • Newer episodes rank higher. The recency bonus has a 2-year half-life.
  • Archived shows rank lower. Show pages and episodes of archived shows (active = false) get their score multiplied by 0.8. Searching an archived show by name still puts it first.

Results

  • One card per result, with a type tag (pick, sponsor, episode, show, person).
  • Episode and sponsor cards also show which show they belong to. A sponsor that has a separate entry per show (e.g. Tailscale for Coder Radio, LINUX Unplugged and Self-Hosted) shows up as separate cards, each with its own show link.
  • Picks and sponsors link straight to their external URL (↗).
  • Results update as you type. Output is escaped, and older responses never replace newer ones.

How it works

  • Pagefind's CLI indexes the built HTML. There are no custom indexing scripts.
  • data-pagefind-body limits what is indexed (see Unused Generated Pages #539). Episode pages add ISO date, show, type and archived meta, and index their tags, sponsor names and pick titles.
  • Each show and person is indexed once. Only page 1 of a show's episode list is indexed, and people who are both host and guest are indexed via their host page.
  • Picks (data/picks/*.yaml) and sponsors have no pages of their own to index:
    • Sponsors get a layout for their existing /sponsors/<name>/ pages. Their show comes from the episodes that list them.
    • Picks get a front-matter-only stub in content/search-index/picks/<name>.md, which renders an index-only page from the data file. The build fails if a stub has no matching data, so a new pick needs a new stub.
  • When the index is missing (e.g. Render previews), the page shows a "not available" message. Colors use only the JB palette.

Builds

  • Prod Dockerfile: an Alpine stage downloads the pinned Pagefind 1.6.0 binary and indexes public, then deletes public/search-index so the pick stub pages don't ship.
  • make dev: the dev container runs hugo server --renderToDisk and indexes the site on first start (a few minutes). After that it re-indexes whenever content, data or themes change. dev-metrics uses --entrypoint hugo.

Testing

test/e2e/test_search.py (Playwright) covers:

  • Ranking: pick, sponsor, show and person promotion; recency; archived shows ranking lower.
  • No duplicates: one show result and one person result.
  • Episode and sponsor show chips.
  • Empty and no-result queries, escaping, and stale-response handling.

Full e2e suite against the production build: 46 passed.

Not covered: Render PR previews don't build an index, so they show the "not available" message.

@CGBassPlayer CGBassPlayer added enhancement New feature, enhancement, or request in progress currently being worked on UX related to user experience labels Jan 17, 2024
@CGBassPlayer
CGBassPlayer marked this pull request as ready for review February 18, 2025 01:00
@CGBassPlayer
CGBassPlayer marked this pull request as draft November 2, 2026 03:37
@CGBassPlayer CGBassPlayer changed the title Initial Search Support Add site search with Pagefind Nov 2, 2026
@CGBassPlayer CGBassPlayer changed the title Add site search with Pagefind Add site search with Pagefind 1.6 (ranked results, show chips, dev auto-index) Nov 8, 2026
@CGBassPlayer
CGBassPlayer changed the base branch from develop to update-hugo-version November 9, 2026 02:43
@CGBassPlayer
CGBassPlayer changed the base branch from update-hugo-version to develop November 9, 2026 02:46

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature, enhancement, or request in progress currently being worked on UX related to user experience

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Search

1 participant