feat(search): replace stale Algolia DocSearch with self-hosted Pagefind

[Vad1mo]

The site search is legacy Algolia DocSearch v2 (layouts/partials/javascript.html), pointed at the goharbor index on the shared BH4D9OD16A app. It is broken in three ways, all verified against the live index and the archived crawler config (algolia/docsearch-configs/configs/goharbor.json):

1. The index is frozen at ~April 2022. It holds 3327 records covering only docs/1.10, 2.0.0–2.5.0, edge and main. Docs 2.6.0 through 2.15.0 are absent entirely, though all are published and return 200.

2. The searched version is neither visible nor selectable. The crawler config declared attributesForFaceting: ["version"], but start_urls was the bare string "https://goharbor.io/docs" with no (?P<version>…) capture group, so nothing ever populated it — a live facets:["*"] query returns no facets at all. The frontend passes no facetFilters either. Results silently mix nine releases with no way to tell them apart.

3. It only ever searched /docs/. start_urls scoped the crawl to that prefix (sitemap-discovered URLs are filtered against it). Sampling ~4000 hits across six queries returned zero URLs outside /docs/ — no blog, community page, CLI docs or home page — even though the search bar renders on every page.

None of this is fixable from this repo: DocSearch v2 is deprecated and algolia/docsearch-configs is archived read-only, so the crawl cannot be re-triggered or re-scoped by anyone here.

Solution

Self-hosted Pagefind, which builds its index from public/ on every deploy — so it cannot drift from the published site.

Scoping is explicit. Every page carries a scope filter: docs pages get their Harbor version, everything else gets site. Queries ask for {scope: {any: [version, "site"]}}, returning exactly one release of the docs plus all unversioned pages in a single query.

The modal filters with All / Docs / Website, where Docs is a split button — the left half selects docs, the right half picks the release:

[ All ]  [ Docs │ 2.15.0 ▾ ]  [ Website ]

• Choosing a release selects Docs in the same action (one step, not two).
• The release list is built at runtime from pagefind.filters(), so it can only offer versions that were actually built. The navbar dropdown, by contrast, reads config.toml and can point at a version that 404s.
• Defaults to the version of the page being read, or the newest indexed release elsewhere.
• Every docs result carries a version chip, so a hit is never ambiguous.

No release is dropped from the index. /docs/edge/ is excluded only because it is a symlink to the same content /docs/main/ is built from — indexing both returned every dev page twice. Both remain browsable.

What else is in here, and why

• Alpine.js 2.1.2 → 3.14.9. The search component needs the v3 API. Existing usage was three inline x-data components (navbar, theme-toggle, render-image), all v3-compatible as written; theme-toggle.html drops its x-init="init()" because v3 auto-invokes init(). This drops IE11, which Pagefind (WASM + dynamic import()) cannot support in any case.
• .nvmrc v14.11.0 → v20. Node 14 is EOL and cannot run the Pagefind CLI.
• Navbar "latest" badge fix. eq $version $latest compared a string against the whole params.versions map, so the tag never rendered. Now compares against $latest.harborversion.

Hugo stays pinned at 0.74.0 — nothing here needs a newer version. (It does not build on current Hugo, but that is pre-existing: .Site.IsServer was removed, and postcss-cli 7.1.2 fails under Hugo's Node permission model. Worth a separate PR.)

Build

npx -y pagefind@1.5.2 --site public runs after hugo in build, production-build and preview-build. make serve builds the index once and serves it from static/ for the session. netlify.toml is unchanged — it already calls these targets.

Verification

Built and tested with the pinned Hugo 0.74.0, not a newer local one.

Check	Result
Version gate	On a 2.14.0 page → only 2.14.0 hits; switch to 2.9.0 → only 2.9.0, plus Website results
Site-wide coverage	From the home page, a blog term returns blog posts and a community term returns /community/ — neither reachable today
Filter round-trip	All → Website → Docs → version switch → All, active state and results correct at each step
edge excluded	0 hits; main present
Alpine v3	Dark mode toggles and persists across reload, image lightbox opens, navbar burger toggles
Keyboard	⌘K/Ctrl-K opens, Esc closes, arrows + Enter navigate
Mobile	Search moved into .navbar-brand; it was otherwise buried behind the burger menu
Link checker	bin/htmltest gives byte-identical output on this branch and on unmodified main (173 pre-existing errors, 0 new)
Index size	1649 pages, 7.8 MB on disk; the browser fetches only the chunks matching the query plus one fragment per shown result

Notes for reviewers

• Pagefind's rule is that once data-pagefind-body exists anywhere on a site, pages without it are excluded. That attribute is therefore the mechanism for both inclusion (docs, CLI docs, blog, community, home) and for excluding edge.
• layouts/ is not per-branch — load-docs.sh copies only docs/ from each release branch — so these template changes apply to every version automatically and need no backport.
• The version facet is derived structurally from the path under content/docs/ (layouts/partials/docs/page-version.html), not from front matter, so a page cannot drop out of version-scoped search by forgetting to declare a version.

[Vad1mo]

NEW

OLD

Below you don't see what version it actually in scope. Above it is obvious

[Copilot]

Pull request overview

Replaces stale Algolia search with a deployment-built Pagefind index and version-aware search modal.

Changes:

• Adds Pagefind indexing and scoped metadata across site content.
• Adds responsive search UI, filters, keyboard navigation, and styling.
• Upgrades Alpine.js and Node; fixes the navbar’s latest-version badge.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
Makefile	Integrates Pagefind into build and serve targets.
.nvmrc	Upgrades Node to v20.
.gitignore	Ignores generated local indexes.
config.toml	Upgrades Alpine.js.
assets/js/search.js	Implements Pagefind search behavior.
assets/sass/search.sass	Styles the search interface.
assets/sass/style.sass	Imports search styles.
assets/sass/dark-mode.sass	Removes obsolete search-input styling.
layouts/_default/baseof.html	Adds the global search modal.
layouts/_default/single.html	Indexes general site pages.
layouts/index.html	Indexes selected homepage content.
layouts/partials/blog/content.html	Indexes blog content.
layouts/partials/cli-docs/layout.html	Indexes CLI documentation.
layouts/partials/css.html	Removes Algolia CSS.
layouts/partials/docs/layout.html	Indexes version-scoped documentation.
layouts/partials/docs/page-version.html	Derives documentation versions.
layouts/partials/javascript.html	Removes Algolia and loads Alpine v3.
layouts/partials/navbar.html	Adds responsive triggers and fixes latest badge.
layouts/partials/search-bar.html	Defines desktop and mobile triggers.
layouts/partials/search.html	Defines the search modal and results UI.
layouts/partials/theme-toggle.html	Adapts initialization for Alpine v3.

Suppressed comments (1)

layouts/partials/search.html:73

• The active state is only visual for this filter, unlike the Docs button. Expose it with aria-pressed so assistive technology can identify the selected filter.

      <button class="search-filters__pill"
              :class="{ 'search-filters__pill--active': activeType === 'Website' }"
              @click="setType('Website')"
              x-show="websiteTypes().length">Website</button>

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (3)

assets/js/search.js:68

• On a cold open, focus is not moved into the modal until the Pagefind import, initialization, and filter request all finish. During that delay focus remains on the obscured trigger, so Tab can move through the background page and bypass trapFocus. Move the existing $nextTick focus block to immediately after this.open = true, before these awaits, and avoid refocusing the input again when initialization completes.

        if (!this.pagefind) {
          try {
            var pagefind = await import('/pagefind/pagefind.js');
            await pagefind.init();

assets/js/search.js:233

• Both asynchronous Pagefind operations can reject (for example, if a lazy index chunk or result fragment fails to load), but this method has no error path. A rejection leaves loading true indefinitely and produces an unhandled promise rejection, so the modal remains stuck on “Searching…”. Catch failures for the current token, clear/reset the UI, and expose a retryable search error; stale-token failures should remain ignored.

        var search = await this.pagefind.debouncedSearch(this.query, opts, 300);
        if (search === null || token !== this.searchToken) return;

        var loaded = await Promise.all(
          search.results.slice(0, 20).map(function (r) { return r.data(); })
        );

assets/js/search.js:107

• Closing the dialog clears the UI but does not invalidate an in-flight search. If Escape is pressed while debouncedSearch() or a result data() load is pending, that request still owns the current token and can repopulate results after close; reopening then shows those stale results for an empty query. Increment searchToken while closing so pending work fails the existing token checks.

      closeModal: function () {
        this.open = false;
        document.documentElement.classList.remove('has-search-open');
        this.query = '';
        this.clearResults();
        this.loading = false;

[Vad1mo]

Picked up the three suppressed comments from the 10 Aug review — all three were valid, and two were regressions I introduced in 323b441. Reproduced each before fixing, re-verified after. Pushed in bfadd24.

closeModal didn't invalidate an in-flight search. I added the search token last round but forgot the close path, so a pending request kept the current token, passed the staleness checks, and wrote into the closed modal.

• Before: mid-flight token=1 | after close token=1 | t2600: results=20 query="" open=false
• After: after close token=2 | t2600: results=0 query=""

No error path on either Pagefind await. A rejected index chunk or result fragment left the spinner up for good plus an unhandled rejection.

• Before: loading=true spinnerVisible=true unhandledRejections=1
• After: loading=false unhandledRejections=0 searchError=true errorVisible=true

Cold-open focus gap. Focus entered the dialog only after import + init + filters resolved, so trapFocus had nothing to contain and Tab walked the page behind an already-visible modal.

• Measured locally: focus entered at 10ms, init finished at 99ms — a ~90ms unprotected window on localhost, considerably worse on a slow connection. Focus now happens before those awaits.

The error state also fixes a silent-degradation problem worth calling out: with the index missing entirely, the modal used to collapse to a bare input with no filters and no explanation, which reads as intentional rather than broken. I hit this myself during testing. It now says "Search is unavailable right now" with a Try again that re-runs initialisation — verified recovering from pagefind=false versions=0 to pagefind=true versions=18, then returning results normally.

Regression-checked afterwards: version gating, All/Docs/Website round-trip, combobox/aria-activedescendant and aria-pressed all still correct; htmltest unchanged.

[bupd]

/lgtm

[wy65701436]

lgtm

[OrlinVasilev]

great stuff