docusaurus-plugin-rangefind 0.3.0

package/README.md

@@ -0,0 +1,127 @@
+# docusaurus-plugin-rangefind
+
+Add fast, fully static search to a [Docusaurus](https://docusaurus.io) site with
+[Rangefind](https://github.com/xjodoin/rangefind) — a search engine that ships a
+**static index** and answers queries in the browser with **HTTP Range
+requests**. No search server, no third-party service, no crawl-time API keys.
+
+At `docusaurus build` time the plugin:
+
+1. Crawls the freshly built HTML in `outDir` and writes a Rangefind index to
+   `build/rangefind/` (via `buildFromCrawl` from `rangefind/crawler`).
+2. Copies the drop-in search web component and its optional theme into
+   `build/_rangefind/`.
+3. Injects the component's `<script type="module">` (and, by default, the theme
+   `<link rel="stylesheet">`) on **every page**.
+
+You then place the `<rangefind-search>` box wherever you want it.
+
+## Install
+
+```bash
+npm install --save-dev docusaurus-plugin-rangefind rangefind
+```
+
+`rangefind` is a runtime peer used at build time (crawler + client bundle);
+`@docusaurus/core` >= 3 is a peer.
+
+## Configure
+
+`docusaurus.config.js`:
+
+```js
+module.exports = {
+  // ...
+  plugins: ["docusaurus-plugin-rangefind"]
+};
+```
+
+Or with options:
+
+```js
+module.exports = {
+  plugins: [
+    ["docusaurus-plugin-rangefind", { theme: true }]
+  ]
+};
+```
+
+## Place the search box
+
+The plugin injects the component's script/style globally but **does not** render
+a search box for you — that would force a duplicate box onto every page with no
+control over placement (this mirrors how other Docusaurus search plugins work).
+Instead, `<rangefind-search>` is a plain custom element, so you drop it in
+wherever you like. Point its `src` at the index, which lives at
+`<baseUrl>rangefind/` (so `/rangefind/` for a root deploy, `/my-repo/rangefind/`
+under a sub-path `baseUrl`).
+
+**Option A — a navbar item (recommended).** Use Docusaurus's built-in `html`
+navbar item type:
+
+```js
+themeConfig: {
+  navbar: {
+    items: [
+      {
+        type: "html",
+        position: "right",
+        value: '<rangefind-search src="/rangefind/" placeholder="Search…"></rangefind-search>'
+      }
+    ]
+  }
+}
+```
+
+**Option B — directly in any Markdown/MDX page.** Because it is a custom
+element, no React wrapper is needed once the script is injected:
+
+```mdx
+<rangefind-search src="/rangefind/" placeholder="Search the docs…"></rangefind-search>
+```
+
+**Option C — a swizzled component.** Swizzle e.g. `Navbar/Content` and render
+`<rangefind-search src="/rangefind/" />` in your JSX. React passes custom
+elements through untouched.
+
+## Options
+
+All options are optional.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | Set `false` to skip indexing and injection entirely (e.g. in a preview build). |
+| `theme` | `boolean` | `true` | Inject the optional `rangefind-search.css` theme link. Set `false` if you style the component yourself. |
+| `baseUrl` | `string` | site `baseUrl` | URL prefix for result URLs and the injected asset tags. Defaults to Docusaurus's own `baseUrl`, which is correct for sub-path deploys. |
+| `outputDir` | `string` | `"rangefind"` | Index directory, relative to `outDir` (absolute paths are used as-is). This is also where your `<rangefind-search src>` should point (`<baseUrl><outputDir>/`). |
+| `assetsDir` | `string` | `"_rangefind"` | Directory (relative to `outDir`) for the copied `rangefind-search.js` / `.css`. |
+
+## Styling
+
+Zero framework is required beyond Docusaurus. The `<rangefind-search>` element
+renders into its **light DOM** with no styling of its own, so:
+
+- The bundled theme (`theme: true`, on by default) gives you a usable look with
+  light/dark palettes out of the box.
+- With Tailwind or any CSS framework, disable the theme (`theme: false`) and use
+  the component's per-part `*-class` attributes (`input-class`, `option-class`,
+  `mark-class`, …) or namespaced `rf-search__*` hook classes.
+
+See the Rangefind monorepo's component reference (the "Search UI component"
+section of `docs/reference.md`) for the full attribute list, class hooks,
+events, and accessibility details — this plugin does not change that API, it
+only wires the component into the Docusaurus build.
+
+## How it works
+
+- **Hooks:** the plugin uses the official `postBuild(props)` lifecycle hook
+  (crawl + asset copy, keyed off `props.outDir`) and `injectHtmlTags()`
+  (global script + optional style in `postBodyTags`).
+- **Asset resolution:** the client bundle and theme are located with
+  `require.resolve("rangefind/element")` and
+  `require.resolve("rangefind/element.css")`, so they always match the installed
+  `rangefind` version; the crawler is loaded via a dynamic
+  `import("rangefind/crawler")`.
+- **Deployment:** Rangefind needs a static host that supports HTTP `Range`
+  requests (GitHub Pages, Netlify, S3/CloudFront, nginx, …). See the Rangefind
+  deployment notes for MIME/caching guidance.

package/index.js

@@ -0,0 +1,113 @@
+"use strict";
+
+// docusaurus-plugin-rangefind — index a built Docusaurus site with Rangefind
+// (a static search engine: static index + HTTP Range requests, no server) and
+// inject the drop-in `<rangefind-search>` web component site-wide.
+//
+// This module is CommonJS on purpose: Docusaurus loads plugin modules with a
+// CJS-first loader, and `require.resolve` gives us the real on-disk paths of
+// the `rangefind/element` bundle and its CSS without executing them. The
+// crawler (`rangefind/crawler`) is ESM in an otherwise-ESM package, so it is
+// pulled in with a dynamic `import()` from inside the async `postBuild` hook —
+// that works from CJS regardless of the target module's format.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_OUTPUT_DIR = "rangefind"; // index dir, relative to outDir
+const DEFAULT_ASSETS_DIR = "_rangefind"; // client asset dir, relative to outDir
+const ASSET_JS = "rangefind-search.js";
+const ASSET_CSS = "rangefind-search.css";
+
+// Docusaurus base URLs always carry a trailing slash; normalize so callers can
+// pass "/base" or "/base/" interchangeably and our string joins never double
+// or drop the separator.
+function normalizeBaseUrl(baseUrl) {
+  const value = String(baseUrl || "/");
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+module.exports = function rangefindPlugin(context = {}, options = {}) {
+  const enabled = options.enabled !== false;
+  const theme = options.theme !== false;
+  const assetsDir = options.assetsDir || DEFAULT_ASSETS_DIR;
+  const outputDir = options.outputDir || DEFAULT_OUTPUT_DIR;
+
+  // Base URL for the injected asset tags. Prefer an explicit override, then the
+  // site's own configured baseUrl so the tag src matches the deployed prefix.
+  const siteBaseUrl = normalizeBaseUrl(
+    options.baseUrl != null ? options.baseUrl : context && context.siteConfig && context.siteConfig.baseUrl
+  );
+
+  return {
+    name: "docusaurus-plugin-rangefind",
+
+    // Official post-build lifecycle hook: the whole site is already emitted to
+    // props.outDir, so we crawl that HTML into a Rangefind index and copy the
+    // search UI assets alongside it.
+    async postBuild(props) {
+      if (!enabled) return;
+
+      const outDir = props.outDir;
+      // buildFromCrawl's baseUrl is the URL prefix stamped onto every result
+      // URL; Docusaurus's own baseUrl is the right default so links resolve on
+      // the deployed site (root-relative under any sub-path deploy).
+      const crawlBaseUrl = normalizeBaseUrl(
+        options.baseUrl != null
+          ? options.baseUrl
+          : props.baseUrl != null
+            ? props.baseUrl
+            : props.siteConfig && props.siteConfig.baseUrl != null
+              ? props.siteConfig.baseUrl
+              : siteBaseUrl
+      );
+
+      const output = path.isAbsolute(outputDir) ? outputDir : path.join(outDir, outputDir);
+
+      // ESM crawler pulled in dynamically from this CJS module.
+      const { buildFromCrawl } = await import("rangefind/crawler");
+      await buildFromCrawl({
+        root: outDir,
+        scanDir: outDir,
+        output,
+        baseUrl: crawlBaseUrl
+      });
+
+      // Copy the two client assets next to the site. Paths resolve through the
+      // `rangefind` package exports map to the real dist files.
+      const assetsOut = path.join(outDir, assetsDir);
+      await fs.promises.mkdir(assetsOut, { recursive: true });
+      const jsSrc = require.resolve("rangefind/element");
+      const cssSrc = require.resolve("rangefind/element.css");
+      await fs.promises.copyFile(jsSrc, path.join(assetsOut, ASSET_JS));
+      await fs.promises.copyFile(cssSrc, path.join(assetsOut, ASSET_CSS));
+    },
+
+    // Inject the search element's script (and, unless disabled, the optional
+    // theme) on every page. The `<rangefind-search>` element itself is NOT
+    // injected here — users place it where they want (navbar html item, MDX,
+    // or a swizzled component); see the README.
+    injectHtmlTags() {
+      if (!enabled) return {};
+      const tags = [
+        {
+          tagName: "script",
+          attributes: {
+            type: "module",
+            src: `${siteBaseUrl}${assetsDir}/${ASSET_JS}`
+          }
+        }
+      ];
+      if (theme) {
+        tags.push({
+          tagName: "link",
+          attributes: {
+            rel: "stylesheet",
+            href: `${siteBaseUrl}${assetsDir}/${ASSET_CSS}`
+          }
+        });
+      }
+      return { postBodyTags: tags };
+    }
+  };
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "docusaurus-plugin-rangefind",
+  "version": "0.3.0",
+  "description": "Docusaurus plugin that indexes your built site with Rangefind (static search over HTTP Range requests, no server) and injects the drop-in <rangefind-search> web component.",
+  "license": "MIT",
+  "author": "Xavier Jodoin <xavier@jodoin.me>",
+  "keywords": [
+    "docusaurus",
+    "docusaurus-plugin",
+    "search",
+    "rangefind",
+    "static-search",
+    "client-side-search"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": ">=3.0.0"
+  },
+  "dependencies": {
+    "rangefind": "^0.3.0"
+  },
+  "devDependencies": {
+    "@docusaurus/core": "^3",
+    "@docusaurus/preset-classic": "^3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xjodoin/rangefind.git",
+    "directory": "packages/docusaurus-plugin-rangefind"
+  },
+  "homepage": "https://github.com/xjodoin/rangefind/tree/main/packages/docusaurus-plugin-rangefind#readme",
+  "bugs": {
+    "url": "https://github.com/xjodoin/rangefind/issues"
+  }
+}