jekyll-pagefind

Overview

Jekyll-Pagefind is a plugin that runs the Pagefind binary for a Jekyll site.

Important

Please use plugin gem version >= 0.3.3. Before that versions are incompatible with current API. See SECURITY.md

Install

Install the gem and add it to your application's Gemfile by running:

bundle add jekyll-pagefind

In your Gemfile:

group :jekyll_plugins do
  # other jekyll plugins
  gem 'jekyll-pagefind' # add pagefind plugin
end

bundle install

If Bundler is not being used to manage dependencies, install the gem by running:

gem install jekyll-pagefind

RubyGems will install the platform-specific package that matches the host OS and CPU. If no matching platform gem is selected, the generic ruby gem raises a clear error telling the user to add the deploy platform to Gemfile.lock.

Use

Jekyll site configuration

_config.yml

plugins:
  # other plugin
  - jekyll-pagefind
# other config
# Optional Jekyll Pagefind Options
jekyll_pagefind:
  output_subdir: pagefind

Jekyll Pagefind options (optional)

These options map to the settings available in Pagefind config files.

For more details, see Pagefind CLI configuration options. jekyll_pagefind supports the following options.

1. output_subdir

The folder where the search bundle is written, relative to Jekyll {{ site.dest }}. The default is pagefind.

Example:

output_subdir: pf # becomes _site/pf

2. exclude_selectors

Pass extra element selectors that Pagefind should ignore when indexing.

Example :

exclude_selectors:
  - "#my_navigation"
  - "blockquote > span"
  - "[id^='prefix-']"

3. keep_index_url

Keeps index.html at the end of search result paths. The default is false.

By default, a file at animals/cat/index.html will be given the URL /animals/cat/. Setting this option to true will result in the URL /animals/cat/index.html.

4. quiet

Logs only errors and warnings while indexing the site.

Pagefind UI

1. Using the Default UI

Using the Default UI is still supported, but it is no longer Pagefind's primary recommendation.

You can add the Pagefind UI to any page with the following snippet. The /pagefind/ directory, or the directory specified by output_subdir in the config, will be created along with its files.

1.1 Using with baseUrl `https://<username|org-name>.github.io/<repo-name>`

<!-- Load the CSS asset using Jekyll's baseurl -->
<script src="{{ '/pagefind/pagefind-ui.js' | relative_url }}"></script>
<!-- Load the JS asset using Jekyll's baseurl -->
<link rel="stylesheet" href="{{ '/pagefind/pagefind-ui.css' | relative_url }}" />

<div id="search"></div>
<script>
    window.addEventListener('DOMContentLoaded', (event) => {
        new PagefindUI({
            element: "#search",
            // Tells Pagefind UI exactly where to find the search bundle folder
            bundlePath: "{{ '/pagefind/' | relative_url }}",
            // Tells Pagefind to correctly prepend the baseurl to search results paths
            baseUrl: "{{ '/' | relative_url }}"
        });
    });
</script>

1.2 Using without baseUrl

<!-- Load the CSS asset using Jekyll's baseurl -->
<script src="{{ '/pagefind/pagefind-ui.js' | relative_url }}"></script>
<!-- Load the JS asset using Jekyll's baseurl -->
<link rel="stylesheet" href="{{ '/pagefind/pagefind-ui.css' | relative_url }}" />

<div id="search"></div>
<script>
    window.addEventListener('DOMContentLoaded', (event) => {
        new PagefindUI({ element: "#search", showSubResults: true });
    });
</script>

1.3 For dark mode

body.dark {
  --pagefind-ui-primary: #eeeeee;
  --pagefind-ui-text: #eeeeee;
  --pagefind-ui-background: #152028;
  --pagefind-ui-border: #152028;
  --pagefind-ui-tag: #152028;
}

For more details, see Using the Default UI.

2. Pagefind Component UI

Add the following snippet to <head>. The /pagefind/ directory, or the directory specified by output_subdir in the config, will be created along with its files.

2.1 Using with baseUrl `https://<username|org-name>.github.io/<repo-name>`

<head>
  <!-- Load the CSS asset using Jekyll's baseurl -->
<script src="{{ '/pagefind/pagefind-component-ui.js' | relative_url }}" type="module"></script>
<!-- Load the JS asset using Jekyll's baseurl -->
<link rel="stylesheet" href="{{ '/pagefind/pagefind-component-ui.css' | relative_url }}" />
</head>
<body>
  <!-- For dark mode wrap with <div data-pf-theme="dark"> -->
  <div data-pf-theme="dark">
    <pagefind-config
      bundle-path="{{ '/pagefind/' | relative_url }}"
      base-url="{{ '/' | relative_url }}">
    </pagefind-config>
    <pagefind-searchbox></pagefind-searchbox>
  </div>
</body>

2.2 Using without baseUrl

<head>
  <!-- Load the CSS asset using Jekyll's baseurl -->
<script src="{{ '/pagefind/pagefind-component-ui.js' | relative_url }}" type="module"></script>
<!-- Load the JS asset using Jekyll's baseurl -->
<link rel="stylesheet" href="{{ '/pagefind/pagefind-component-ui.css' | relative_url }}" />
</head>
<body>
  <!-- For dark mode wrap with <div data-pf-theme="dark"> -->
  <div data-pf-theme="dark">
    <pagefind-searchbox></pagefind-searchbox>
  </div>
</body>

2.3 For dark mode

@media (prefers-color-scheme: dark) {
  :root {
    --pf-text: #e5e5e5;
    --pf-text-secondary: #a0a0a0;
    --pf-text-muted: #949494;
    --pf-background: #1a1a1a;
    --pf-border: #333;
    --pf-border-focus: #555;
    --pf-skeleton: #2a2a2a;
    --pf-skeleton-shine: #333;
    --pf-hover: #252525;
    --pf-mark: #e5e5e5;
    --pf-scroll-shadow: rgba(255, 255, 255, 0.1);
    --pf-outline-focus: #58a6ff;

    --pf-shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.3);
    --pf-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
    --pf-shadow-lg: 0 16px 48px rgba(0, 0, 0, 0.5);

    --pf-error-bg: #2a1a1a;
    --pf-error-border: #5c2828;
    --pf-error-text: #f87171;
    --pf-error-text-secondary: #ef4444;
  }
}

For more details, see Pagefind Component UI.

Contributing

Maintainer Release Notes

This gem is published as platform-specific packages so users only download the binary for their host OS.

Build the current host variant:

make build

Build every supported variant:

make build-all

Publish the built platform gems for a version:

make publish

GitHub Actions trusted publishing is supported.

To enable it on RubyGems.org for this repo:

Open the jekyll-pagefind gem page.
Go to Trusted publishers.
Create a publisher with repository phothinmg/jekyll-pagefind, workflow filename release.yml, and environment release.

After that, pushing a tag like v0.3.2 will run .github/workflows/release.yml and publish all built gems without a stored API token or manual OTP entry.

bin/build-platform-gems currently maps these asset folders to RubyGems platforms:

ruby -> ruby (generic fallback gem with no bundled binary)
assets/linux-x64 -> x86_64-linux-gnu, x86_64-linux-musl
assets/linux-arm64 -> aarch64-linux-gnu, aarch64-linux-musl
assets/macos-x64 -> x86_64-darwin
assets/macos-arm64 -> arm64-darwin
assets/windows-x64 -> x64-mingw32, x64-mingw-ucrt
assets/windows-arm64 -> arm64-mingw32, arm64-mingw-ucrt

Bug reports and pull requests are welcome on GitHub at https://github.com/phothinmg/jekyll-pagefind. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Jekyll::Pagefind project's codebase, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.

jekyll-pagefind

Runtime

jekyll-pagefind

Overview

Install

Use

Jekyll site configuration

Jekyll Pagefind options (optional)

1. output_subdir

2. exclude_selectors

3. keep_index_url

4. quiet

Pagefind UI

1. Using the Default UI

1.1 Using with baseUrl https://<username|org-name>.github.io/<repo-name>

1.2 Using without baseUrl

1.3 For dark mode

2. Pagefind Component UI

2.1 Using with baseUrl https://<username|org-name>.github.io/<repo-name>

2.2 Using without baseUrl

2.3 For dark mode

Contributing

Maintainer Release Notes

License

Code of Conduct

1.1 Using with baseUrl `https://<username|org-name>.github.io/<repo-name>`

2.1 Using with baseUrl `https://<username|org-name>.github.io/<repo-name>`