Pagefind on GitHub Pages: Fix Missing Search Assets After Deploy

Build Pagefind after the site output#

Pagefind indexes generated HTML. Run the site generator first, then point Pagefind at the resulting directory:

1
pnpm build
2
pnpm exec pagefind --site dist --output-subdir pagefind
3
find dist/pagefind -maxdepth 2 -type f | sort | sed -n '1,20p'

The default Pagefind output directory is pagefind, and --output-subdir lets you choose a different directory relative to the processed site. If your Astro integration already runs Pagefind as part of pnpm build, do not run a second indexing pass blindly; inspect the existing build log and output instead.

The order matters. Running Pagefind before Astro writes the final HTML produces an empty or incomplete index. Running it after the build but deploying only the source checkout produces a correct local directory that never reaches GitHub Pages.

Deploy the generated directory, not just the repository source#

GitHub Pages supports a custom Actions workflow for static site generators. A safe workflow has a build job that installs dependencies, generates the site, runs Pagefind, and uploads the final directory as a Pages artifact. The deploy job then publishes that artifact:

1
- name: Build site
2
  run: |
3
    pnpm install --frozen-lockfile
4
    pnpm build
5
    pnpm exec pagefind --site dist --output-subdir pagefind
6

7
- name: Upload Pages artifact
8
  uses: actions/upload-pages-artifact@v4
9
  with:
10
    path: dist

The action names and permissions belong in the complete workflow, including actions/configure-pages and actions/deploy-pages. The important Pagefind detail is the artifact path: it must be the directory that contains both the HTML and pagefind/ output.

After deployment, test the exact public path instead of relying on a successful workflow status:

1
curl -fsSI https://USER.github.io/REPOSITORY/pagefind/pagefind.js
2
curl -fsSI https://USER.github.io/REPOSITORY/en/

For a user site at USER.github.io, omit /REPOSITORY. For a project site, keep the repository base path in both the HTML asset URLs and the Pagefind client configuration.

Match Pagefind’s bundle path to the site base#

Pagefind UI can load its bundle from a non-standard directory. If your project is served at the domain root, the path is usually /pagefind/:

1
new PagefindUI({
2
  element: '#search',
3
  bundlePath: '/pagefind/',
4
});

On a project Pages site, the public URL is commonly /REPOSITORY/pagefind/, not /pagefind/. Use the base URL supplied by your static-site build and append pagefind/ once. Do not concatenate a leading slash twice, and do not hard-code a domain when the same artifact is previewed on another host.

If the browser requests /pagefind/pagefind.js but the deployed file is /REPOSITORY/pagefind/pagefind.js, the server can be healthy while search fails. Use the browser network panel or the HTML source to compare the requested URL with the artifact tree.

Check source-based Jekyll deployment boundaries#

A branch-based Pages build can run Jekyll over the repository rather than publish the output produced by your Astro job. That is a different pipeline. If Pagefind is generated into an underscore-prefixed directory such as _pagefind, a Jekyll configuration may need an explicit include entry; alternatively, choose the ordinary pagefind output directory and publish the finished static artifact.

Do not add a Jekyll workaround until you know which deployment source is active. GitHub Pages can publish from a branch or from a custom Actions workflow. The workflow approach is usually clearer for Astro because it lets one job control the order of Astro build, Pagefind indexing, and artifact upload.

For a branch-based Jekyll site, the relevant shape is:

1
include:
2
  - _pagefind

That setting only helps if the Jekyll build is the process that owns the source directory. It does not copy a pagefind/ directory from a local machine into a remote Pages deployment.

Verify the deployed index separately from the UI#

Use a short checklist whenever the search box is blank or returns no results:

1. Inspect dist/pagefind/ after the build.
2. Inspect the uploaded Pages artifact or workflow log to confirm the directory is present.
3. Request the public pagefind.js URL with the correct base path.
4. Check that the client bundlePath points to that same directory.
5. Open one generated HTML file and confirm its asset URLs use the site’s base.
6. Search for a distinctive phrase from a page that is definitely in the artifact.

If the JavaScript file loads but the search index does not, compare the index paths in the network panel and check whether a cache is serving an older HTML file. If every Pagefind asset is missing, return to the build order and artifact path; changing ranking or language configuration will not create files that were never deployed.

For multilingual Astro sites, keep the locale boundary separate from the hosting boundary. The Pagefind multilingual search guide explains how html lang selects language-aware indexes; this article addresses whether those indexes reach GitHub Pages at all.

FAQ#