Pagefind

1.5.0 · active · verified Sat Apr 11

Pagefind is a library for performant, low-bandwidth, fully static search. The `pagefind-bin` Python package provides a convenient wrapper to install and manage the Pagefind binary for use in Python projects, making its CLI tools accessible. The current version is 1.5.0, and it typically releases updates in sync with the upstream Pagefind binary releases.

Warnings

breaking Calling `PagefindBinary().install()` without a specific `version` argument will download the *latest available* Pagefind CLI binary. This can silently upgrade to a new major version of the Pagefind CLI (e.g., 2.x.x), introducing breaking changes to its command-line arguments, output format, or behavior, even if the `pagefind-bin` Python package version remains stable.
Fix: Always pin the Pagefind CLI binary version you intend to use in production: `pagefind.install(version='1.x.x')` to prevent unexpected upgrades and ensure consistent behavior.
gotcha The `pagefind-bin` library is primarily a wrapper to *install and locate* the Pagefind CLI binary. It does not provide a direct Python API for generating search indexes or running search queries within Python code. Interaction with the core Pagefind functionality must be done by executing the installed binary via `subprocess` or similar methods.
Fix: Utilize Python's `subprocess` module to run the Pagefind binary obtained via `PagefindBinary().path()`, passing required CLI arguments as demonstrated in the quickstart.
gotcha The Pagefind CLI binary installed by `pagefind-bin` is typically placed in a project-specific or user-specific directory and is *not automatically added to your system's PATH*. Attempting to run `pagefind` directly in a shell or `subprocess` without specifying the full path will likely result in a 'command not found' error.
Fix: Always retrieve the full path to the binary using `PagefindBinary().path()` and use this path when executing the command via `subprocess`.

Install

pip install pagefind-bin Install the pagefind-bin package

Imports

PagefindBinary
```
from pagefind_bin import PagefindBinary
```
The primary interaction is with the PagefindBinary class to install and locate the Pagefind CLI tool.

Quickstart

This quickstart demonstrates how to install the Pagefind CLI binary using `pagefind-bin`, retrieve its path, and then execute a Pagefind command via `subprocess` to build a search index for a static site. Remember to replace 'my_static_site_output' with your actual static site's build directory.

import os
import subprocess
from pagefind_bin import PagefindBinary

# 1. Initialize and install the Pagefind binary
pagefind = PagefindBinary()
# It's recommended to pin the version for production to avoid unexpected updates:
# pagefind.install(version="1.x.x")
pagefind.install()

# 2. Get the path to the installed binary
pagefind_cli_path = pagefind.path()
print(f"Pagefind CLI installed at: {pagefind_cli_path}")

# 3. Use the Pagefind CLI to build an index (example)
# For this example to work, you'd need some static files in 'my_static_site_output'.
# Replace 'my_static_site_output' with your actual static site build directory.
source_directory = "my_static_site_output" # e.g., 'build', '_site', 'public'
output_directory = os.path.join(source_directory, "pagefind") # Default output dir for Pagefind

# Create a dummy directory and file for demonstration if it doesn't exist
if not os.path.exists(source_directory):
    os.makedirs(source_directory, exist_ok=True)
    with open(os.path.join(source_directory, "index.html"), "w") as f:
        f.write("<html><body><h1>Hello Pagefind!</h1></body></html>")
    print(f"Created dummy static site at {source_directory}")

try:
    print(f"Running Pagefind build on {source_directory}...")
    command = [pagefind_cli_path, "--source", source_directory, "--output", output_directory]
    result = subprocess.run(command, capture_output=True, text=True, check=True)
    print("Pagefind build successful.")
    print("STDOUT:", result.stdout)
    if result.stderr:
        print("STDERR:", result.stderr)
    print(f"Search index generated in {output_directory}")
except subprocess.CalledProcessError as e:
    print(f"Pagefind build failed: {e}")
    print("STDOUT:", e.stdout)
    print("STDERR:", e.stderr)
except FileNotFoundError:
    print(f"Error: Pagefind binary not found at {pagefind_cli_path}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →