Skip to content
staticcanvasPublic

Latest commit

 

History

148 Commits

Folders and files

Repository files navigation

Hawk Banner

license gitlab-pipeline codecov documentation gitlab-issues

gitlab-release gitlab-tag

npm-version npm-downloads

jsr-version jsdelivr-hitsperweek

runtime-badge

Themeable, pluggable command-palette search UI for static sites, powered by Pagefind.


🔹 Read the full documentation here

🔹 Use the playground here

📚Table of Contents

Features

  • Pagefind-backed — chunked, lazily-loaded, typo-tolerant search index.
  • Scale-safe result hydration — bounded concurrent fragment loading and progressive rendering keep Hawk's network and DOM work predictable for both small and very large indexes.
  • Developer-configured tabs — auto-derived category pills, or explicit Pagefind-filter tabs.
  • Fit / medium / compact density modes with a persisted in-modal toggle.
  • Two-pane keyboard navigation — Tab between input, filters, results, and preview.
  • Configurable layout — scale, position, offset, columns, and a JS-driven breakpoint.
  • Theme and animation plugin systems — a TypeFlow typewriter driver ships built-in, alongside a zero-dependency instant driver.
  • Structured inline filters — category:Guides responsive parses out a filter as you type.
  • Result metadata — dates, tags, related pages, and a pin system, each independently themeable and configurable.
  • Built-in trigger element and Pagefind attribution, so no hand-built markup is required.
  • Accessible by default — a real modal focus trap, graceful fallback if Pagefind fails to load, and full i18n via config.strings.

See Resources below for the full feature reference.

Installation

npm install @staticcanvas/hawk
npm install --save-dev pagefind
# Optional: the official TypeFlow animation driver
npm install @staticcanvas/typeflow

pagefind is a real dependency (hawk has nothing to search without an index). @staticcanvas/typeflow is an optional peer dependency — only needed when importing Hawk's official TypeFlow animation adapter. Hawk core and the TypeFlow visual theme remain independent.

Quick start

import { HawkSearch } from '@staticcanvas/hawk';
import '@staticcanvas/hawk/css';

new HawkSearch({
  index: '/pagefind/',
  trigger: { container: 'body' },
});

Hawk hydrates Pagefind result fragments in ordered batches: up to 6 requests run concurrently, the first completed batch renders immediately, and loading stops once maxResults is filled. Large or exclusion-heavy indexes are bounded to maxCandidateResults candidates (by default, three times maxResults). Both limits are configurable; see the API reference.

That is the complete zero-config path — trigger renders hawk's own trigger button, so no host markup is required. See Getting started in the docs for the full TypeFlow-themed setup, frontmatter/metadata mapping, and every config option.

Build from source

git clone https://github.com/staticcanvas/hawk.git
cd hawk
npm install
npm run build   # core + optional (theme-typeflow, animation-typeflow, debug, metrics) bundles
npm test        # vitest, jsdom

To build and preview the docs site itself (Hugo + Pagefind, requires Hugo on PATH):

npm run docs:serve

See Development & NPM Scripts for the full script reference.

Acknowledgments

Hawk's development and distribution are supported by these services:

  • jsDelivr — open-source CDN delivery.
  • UNPKG — CDN delivery for npm packages.
  • npm — package registry and distribution.
  • JSR — JavaScript and TypeScript package registry.
  • Shields.io — project and status badges.
  • GitHub — source hosting, CI/CD, releases, and documentation hosting.
  • Codecov — test coverage reporting.

Resources

Contributing

Contributions are welcome. For a substantial change, first open an issue to discuss the proposal. For smaller fixes:

  1. Fork the project, then clone your fork: git clone https://github.com/YOUR_USERNAME/hawk.git.

  2. Enter the checkout: cd hawk.

  3. Install the locked dependencies: npm ci.

  4. Create a branch from develop: git switch develop && git switch -c feature/feature-name.

  5. Make your changes, then run npm run lint and npm test.

  6. Commit and push: git commit -m 'Add feature name' && git push -u origin feature/feature-name.

  7. Open a pull request targeting develop:

    Open a GitHub pull request

Links

Development & NPM Scripts

Script Purpose
npm run dev Vite dev server
npm run serve:demo Opens the local web utility demo in Vite
npm run build Builds core + optional (theme-typeflow, animation-typeflow, debug, metrics) bundles
npm run dev:typeflow Builds hawk and copies the bundle + a preview Pagefind index into the sibling typeflow checkout's docs site, for live prototyping
npm run pagefind:index Wraps pagefind --site <dir> — see scripts/pagefind-index.mjs
npm test / npm run test:coverage Vitest (jsdom) — unit coverage
npm run test:bun / npm run test:coverage:bun Bun test runner, with optional coverage
npm run test:e2e Playwright, real Chromium against a real built docs site + Pagefind index (not a fixture) — builds the docs site with a localhost baseURL override first. Runs as a required browser check in GitHub Actions.
npm run lint / npm run lint:fix ESLint
npm run format Formats the repository with Prettier
npm run docs:build / npm run docs:serve Builds and serves hawk's own Hugo docs site
npm run themes:css Generates one small standalone CSS file per gallery/template theme into docs/static/assets/themes/ — see scripts/generate-theme-css.mjs
npm run docs:scss Compiles docs/static/assets/scss/*.scss into docs/static/assets/docs.css/playground.css — see scripts/compile-docs-scss.mjs. Also runs automatically as part of docs:build/docs:serve
npm run check:size Enforces the gzip bundle size budget
npm run check:jsr Validates the JSR package configuration and dry-run contents
npm run validate:release CI release-artifact validation
npm run check:quality Builds, checks the bundle size, and runs the Vitest suite
npm run bench:size Compares bundle sizes against a selected Git reference

License

Distributed under the MIT License. See LICENSE for details.

CI and release setup is documented in GitHub Actions.

Releases

Packages

Contributors

Languages