mkdocs-rangefind 0.1.0__tar.gz

mkdocs_rangefind-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python / packaging artifacts, scoped to this integration directory.
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Test artifacts written during the run.
+.pytest_cache/
+test/fixture/site/
+test/fixture/node_modules/

mkdocs_rangefind-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: mkdocs-rangefind
+Version: 0.1.0
+Summary: MkDocs plugin that builds a Rangefind static search index and injects the search widget after every build.
+Project-URL: Homepage, https://github.com/xjodoin/rangefind
+Project-URL: Repository, https://github.com/xjodoin/rangefind
+Project-URL: Issues, https://github.com/xjodoin/rangefind/issues
+Author-email: Xavier Jodoin <xavier@jodoin.me>
+License: MIT
+Keywords: mkdocs,mkdocs-plugin,rangefind,search,static-search
+Classifier: Framework :: MkDocs
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.8
+Requires-Dist: mkdocs>=1.4
+Description-Content-Type: text/markdown
+
+# mkdocs-rangefind
+
+An MkDocs plugin that wires [Rangefind](https://github.com/xjodoin/rangefind)
+static search into your docs site. After MkDocs builds your site, the plugin
+crawls the rendered HTML into a static, range-request search index and injects
+the Rangefind search widget into every page — so you get working, serverless
+search with **zero manual HTML editing**.
+
+## How it works (and the one prerequisite)
+
+Rangefind is a Node.js tool; MkDocs is a Python static-site generator. There is
+no way to run Rangefind's indexing logic from pure Python, so this plugin is a
+small, honest bridge: its MkDocs lifecycle hooks **shell out to the Rangefind
+Node CLI** after the site is built.
+
+**Prerequisite:** Node.js (>= 22) and the `rangefind` npm package must be
+reachable from your MkDocs project directory. The simplest setup:
+
+```bash
+npm install rangefind        # adds ./node_modules/rangefind + the CLI bin
+pip install mkdocs-rangefind
+```
+
+With `rangefind` installed locally, both `npx rangefind` (the index build) and
+Node's module resolution (locating the widget's JS/CSS assets) work offline,
+including in CI.
+
+## Usage
+
+Add the plugin to `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search        # optional; Rangefind replaces the need for it
+  - rangefind
+```
+
+Then `mkdocs build` (or `mkdocs gh-deploy`). The plugin will:
+
+1. Run `rangefind build <site_dir> --output <site_dir>/rangefind --base-url <…>`
+   to crawl the built HTML and produce the index under `site/rangefind/`.
+2. Copy the search Web Component assets into `site/_rangefind/`.
+3. Inject a `<script type="module">` for the component, an optional theme
+   `<link>`, and (by default) a `<rangefind-search>` box on every page.
+
+That's it — search works on the deployed static site with no server.
+
+## Configuration
+
+All options are optional. Defaults shown.
+
+```yaml
+plugins:
+  - rangefind:
+      enabled: true            # master switch; false = complete no-op
+      base_url: ""             # URL prefix baked into result links stored in
+                               # the index (CLI --base-url). Empty = derive from
+                               # mkdocs `site_url` path, falling back to "/".
+      output_dir: rangefind    # index output dir, relative to the built site
+      assets_dir: _rangefind   # where the widget JS/CSS are copied, rel. to site
+      theme: false             # also inject the optional framework-free stylesheet
+      node_command: npx        # command used to run the Rangefind CLI
+      placement: body_end      # "body_end" | "manual" (see below)
+      selector: ""             # optional literal HTML marker to place the widget after
+      placeholder: Search      # input placeholder for the injected element
+      element_attributes: {}   # extra attributes for <rangefind-search>
+      element_js_path: ""       # explicit path to rangefind-search.js (advanced)
+      element_css_path: ""      # explicit path to rangefind-search.css (advanced)
+```
+
+### `base_url`
+
+This is passed to the crawler as `--base-url` and controls the URL prefix stored
+in the **result links** inside the index. Left empty, the plugin derives it from
+your MkDocs `site_url` path (e.g. `https://example.com/docs/` → `/docs/`),
+falling back to `/`. Set it explicitly if you need a different prefix. Note this
+is unrelated to where the widget loads the index from — that is always resolved
+as a path *relative to each page*, so nested and subpath-deployed sites work
+without configuration.
+
+### Placement modes
+
+- **`body_end`** (default): the plugin injects
+  `<rangefind-search src="…"></rangefind-search>` right before `</body>` on every
+  page. Search "just works" out of the box.
+- **`manual`**: the plugin injects the component's `<script>` (and theme `<link>`
+  if `theme: true`) but does **not** inject the `<rangefind-search>` element.
+  Hand-place it yourself in a
+  [theme override](https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir),
+  e.g. `<rangefind-search src="/rangefind/"></rangefind-search>`. Use this when
+  you want the search box in a specific spot (a header, a sidebar) rather than at
+  the end of the body.
+
+  ```yaml
+  plugins:
+    - rangefind:
+        placement: manual
+  ```
+
+- **`selector`**: a middle ground. Provide a literal HTML substring that appears
+  in your rendered pages (for example a placeholder you put in a template or
+  Markdown page: `<div id="rangefind"></div>`). The `<rangefind-search>` element
+  is inserted immediately after the first occurrence of that exact string. If the
+  marker is not found on a page, the plugin falls back to `body_end`.
+
+### Styling / Tailwind
+
+The `<rangefind-search>` component renders into **light DOM** and ships no
+styling of its own, so your site's CSS applies directly. For manual placement
+you can pass Tailwind (or any) classes through the component's `*-class`
+attributes via `element_attributes`:
+
+```yaml
+plugins:
+  - rangefind:
+      element_attributes:
+        input-class: "w-full border rounded px-3 py-2"
+        mark-class: "bg-yellow-200"
+        hotkey: true      # boolean attributes: use `true`
+        router: true
+```
+
+The full attribute and class-hook vocabulary (`input-class`, `option-class`,
+`mark-class`, …, plus attributes like `page-size`, `debounce`, `suggest`,
+`hotkey`, `router`) is documented in the Rangefind monorepo's
+[reference guide](https://github.com/xjodoin/rangefind/blob/main/docs/reference.md#search-ui-component)
+— this plugin does not duplicate it, it just forwards attributes verbatim.
+
+### Asset resolution
+
+The plugin needs the component's `rangefind-search.js` / `.css`. Rather than
+guess where npm installed them, it asks Node to resolve them through the
+`rangefind` package's own export map (`rangefind/element` and
+`rangefind/element.css`). This is robust across npm/pnpm/yarn layouts because it
+uses the package's declared entry points rather than assuming a path. If you have
+an unusual setup, set `element_js_path` / `element_css_path` explicitly (paths
+are resolved relative to the MkDocs project directory).
+
+## MkDocs hooks used
+
+- `on_post_build` — builds the index (shell-out) and copies the widget assets.
+- `on_post_page` — injects the `<script>`/`<link>`/`<rangefind-search>` tags,
+  computing correct page-relative asset paths for nested pages.
+
+## License
+
+MIT

mkdocs_rangefind-0.1.0/README.md

@@ -0,0 +1,147 @@
+# mkdocs-rangefind
+
+An MkDocs plugin that wires [Rangefind](https://github.com/xjodoin/rangefind)
+static search into your docs site. After MkDocs builds your site, the plugin
+crawls the rendered HTML into a static, range-request search index and injects
+the Rangefind search widget into every page — so you get working, serverless
+search with **zero manual HTML editing**.
+
+## How it works (and the one prerequisite)
+
+Rangefind is a Node.js tool; MkDocs is a Python static-site generator. There is
+no way to run Rangefind's indexing logic from pure Python, so this plugin is a
+small, honest bridge: its MkDocs lifecycle hooks **shell out to the Rangefind
+Node CLI** after the site is built.
+
+**Prerequisite:** Node.js (>= 22) and the `rangefind` npm package must be
+reachable from your MkDocs project directory. The simplest setup:
+
+```bash
+npm install rangefind        # adds ./node_modules/rangefind + the CLI bin
+pip install mkdocs-rangefind
+```
+
+With `rangefind` installed locally, both `npx rangefind` (the index build) and
+Node's module resolution (locating the widget's JS/CSS assets) work offline,
+including in CI.
+
+## Usage
+
+Add the plugin to `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search        # optional; Rangefind replaces the need for it
+  - rangefind
+```
+
+Then `mkdocs build` (or `mkdocs gh-deploy`). The plugin will:
+
+1. Run `rangefind build <site_dir> --output <site_dir>/rangefind --base-url <…>`
+   to crawl the built HTML and produce the index under `site/rangefind/`.
+2. Copy the search Web Component assets into `site/_rangefind/`.
+3. Inject a `<script type="module">` for the component, an optional theme
+   `<link>`, and (by default) a `<rangefind-search>` box on every page.
+
+That's it — search works on the deployed static site with no server.
+
+## Configuration
+
+All options are optional. Defaults shown.
+
+```yaml
+plugins:
+  - rangefind:
+      enabled: true            # master switch; false = complete no-op
+      base_url: ""             # URL prefix baked into result links stored in
+                               # the index (CLI --base-url). Empty = derive from
+                               # mkdocs `site_url` path, falling back to "/".
+      output_dir: rangefind    # index output dir, relative to the built site
+      assets_dir: _rangefind   # where the widget JS/CSS are copied, rel. to site
+      theme: false             # also inject the optional framework-free stylesheet
+      node_command: npx        # command used to run the Rangefind CLI
+      placement: body_end      # "body_end" | "manual" (see below)
+      selector: ""             # optional literal HTML marker to place the widget after
+      placeholder: Search      # input placeholder for the injected element
+      element_attributes: {}   # extra attributes for <rangefind-search>
+      element_js_path: ""       # explicit path to rangefind-search.js (advanced)
+      element_css_path: ""      # explicit path to rangefind-search.css (advanced)
+```
+
+### `base_url`
+
+This is passed to the crawler as `--base-url` and controls the URL prefix stored
+in the **result links** inside the index. Left empty, the plugin derives it from
+your MkDocs `site_url` path (e.g. `https://example.com/docs/` → `/docs/`),
+falling back to `/`. Set it explicitly if you need a different prefix. Note this
+is unrelated to where the widget loads the index from — that is always resolved
+as a path *relative to each page*, so nested and subpath-deployed sites work
+without configuration.
+
+### Placement modes
+
+- **`body_end`** (default): the plugin injects
+  `<rangefind-search src="…"></rangefind-search>` right before `</body>` on every
+  page. Search "just works" out of the box.
+- **`manual`**: the plugin injects the component's `<script>` (and theme `<link>`
+  if `theme: true`) but does **not** inject the `<rangefind-search>` element.
+  Hand-place it yourself in a
+  [theme override](https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir),
+  e.g. `<rangefind-search src="/rangefind/"></rangefind-search>`. Use this when
+  you want the search box in a specific spot (a header, a sidebar) rather than at
+  the end of the body.
+
+  ```yaml
+  plugins:
+    - rangefind:
+        placement: manual
+  ```
+
+- **`selector`**: a middle ground. Provide a literal HTML substring that appears
+  in your rendered pages (for example a placeholder you put in a template or
+  Markdown page: `<div id="rangefind"></div>`). The `<rangefind-search>` element
+  is inserted immediately after the first occurrence of that exact string. If the
+  marker is not found on a page, the plugin falls back to `body_end`.
+
+### Styling / Tailwind
+
+The `<rangefind-search>` component renders into **light DOM** and ships no
+styling of its own, so your site's CSS applies directly. For manual placement
+you can pass Tailwind (or any) classes through the component's `*-class`
+attributes via `element_attributes`:
+
+```yaml
+plugins:
+  - rangefind:
+      element_attributes:
+        input-class: "w-full border rounded px-3 py-2"
+        mark-class: "bg-yellow-200"
+        hotkey: true      # boolean attributes: use `true`
+        router: true
+```
+
+The full attribute and class-hook vocabulary (`input-class`, `option-class`,
+`mark-class`, …, plus attributes like `page-size`, `debounce`, `suggest`,
+`hotkey`, `router`) is documented in the Rangefind monorepo's
+[reference guide](https://github.com/xjodoin/rangefind/blob/main/docs/reference.md#search-ui-component)
+— this plugin does not duplicate it, it just forwards attributes verbatim.
+
+### Asset resolution
+
+The plugin needs the component's `rangefind-search.js` / `.css`. Rather than
+guess where npm installed them, it asks Node to resolve them through the
+`rangefind` package's own export map (`rangefind/element` and
+`rangefind/element.css`). This is robust across npm/pnpm/yarn layouts because it
+uses the package's declared entry points rather than assuming a path. If you have
+an unusual setup, set `element_js_path` / `element_css_path` explicitly (paths
+are resolved relative to the MkDocs project directory).
+
+## MkDocs hooks used
+
+- `on_post_build` — builds the index (shell-out) and copies the widget assets.
+- `on_post_page` — injects the `<script>`/`<link>`/`<rangefind-search>` tags,
+  computing correct page-relative asset paths for nested pages.
+
+## License
+
+MIT

mkdocs_rangefind-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mkdocs-rangefind"
+version = "0.1.0"
+description = "MkDocs plugin that builds a Rangefind static search index and injects the search widget after every build."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Xavier Jodoin", email = "xavier@jodoin.me" }]
+keywords = ["mkdocs", "mkdocs-plugin", "search", "rangefind", "static-search"]
+classifiers = [
+    "Framework :: MkDocs",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = ["mkdocs>=1.4"]
+
+[project.urls]
+Homepage = "https://github.com/xjodoin/rangefind"
+Repository = "https://github.com/xjodoin/rangefind"
+Issues = "https://github.com/xjodoin/rangefind/issues"
+
+# The MkDocs plugin entry-point group is "mkdocs.plugins" (confirmed against the
+# installed mkdocs package). The name on the left ("rangefind") is what users put
+# under `plugins:` in mkdocs.yml.
+[project.entry-points."mkdocs.plugins"]
+rangefind = "mkdocs_rangefind.plugin:RangefindPlugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mkdocs_rangefind"]

mkdocs_rangefind-0.1.0/src/mkdocs_rangefind/__init__.py

@@ -0,0 +1,3 @@
+"""MkDocs plugin for Rangefind static search."""
+
+__version__ = "0.1.0"

mkdocs_rangefind-0.1.0/src/mkdocs_rangefind/plugin.py

@@ -0,0 +1,305 @@
+"""Rangefind MkDocs plugin.
+
+MkDocs is a Python static-site generator; Rangefind is a Node.js tool. There is
+no way to run Rangefind's indexing logic from pure Python, so this plugin does
+the honest thing: after MkDocs finishes building the site it *shells out* to the
+Rangefind Node CLI (``npx rangefind build <site_dir>``) to crawl the freshly
+rendered HTML into a static, range-request search index, then copies the
+Rangefind search Web Component assets into the site and injects the widget tags
+into every rendered page.
+
+Prerequisite: Node.js and the ``rangefind`` npm package must be reachable from
+the MkDocs project directory (typically ``npm install rangefind`` so that
+``npx rangefind`` and Node's module resolution both find it).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from urllib.parse import urlsplit
+
+from mkdocs.config import config_options
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin
+from mkdocs.utils import get_relative_url
+
+try:  # MkDocs >= 1.2 ships a namespaced logger helper.
+    from mkdocs.plugins import get_plugin_logger
+
+    log = get_plugin_logger(__name__)
+except ImportError:  # pragma: no cover - very old MkDocs
+    import logging
+
+    log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+
+
+class RangefindPlugin(BasePlugin):
+    """Build a Rangefind index after the site is built and inject the widget."""
+
+    # MkDocs uses the classic tuple-based config scheme (name, option) pairs.
+    config_scheme = (
+        # Master switch. When false the plugin is a complete no-op.
+        ("enabled", config_options.Type(bool, default=True)),
+        # URL prefix baked into the *result links* stored in the index
+        # (passed to the CLI as --base-url). Empty string => derive from the
+        # MkDocs `site_url` path (falling back to "/"). Set explicitly when the
+        # index's stored URLs need a specific prefix.
+        ("base_url", config_options.Type(str, default="")),
+        # Index output directory, relative to the built site_dir.
+        ("output_dir", config_options.Type(str, default="rangefind")),
+        # Where the Web Component JS/CSS assets are copied, relative to site_dir.
+        ("assets_dir", config_options.Type(str, default="_rangefind")),
+        # Include the optional framework-free theme stylesheet. Off by default:
+        # the component is headless and inherits the host page's CSS.
+        ("theme", config_options.Type(bool, default=False)),
+        # Command used to run the Rangefind CLI. "npx" resolves the local
+        # `rangefind` install; can be pointed at a specific binary in CI.
+        ("node_command", config_options.Type(str, default="npx")),
+        # Where to place the <rangefind-search> element:
+        #   "body_end" (default) - injected right before </body> on every page.
+        #   "manual"             - not injected; you hand-place it in a theme
+        #                          override. Script/CSS are still injected.
+        ("placement", config_options.Choice(("body_end", "manual"), default="body_end")),
+        # Optional literal HTML marker. When set (and placement != manual), the
+        # <rangefind-search> element is inserted immediately after the first
+        # occurrence of this exact substring instead of before </body> (e.g.
+        # '<div id="rangefind">'). Falls back to body_end if not found.
+        ("selector", config_options.Type(str, default="")),
+        # Input placeholder text for the injected element.
+        ("placeholder", config_options.Type(str, default="Search")),
+        # Arbitrary extra attributes for the injected <rangefind-search> element
+        # (e.g. {hotkey: true, router: true, input-class: "w-full"}).
+        ("element_attributes", config_options.Type(dict, default={})),
+        # Explicit paths to the component assets. When unset the plugin asks
+        # Node to resolve them from the installed `rangefind` package.
+        ("element_js_path", config_options.Type(str, default="")),
+        ("element_css_path", config_options.Type(str, default="")),
+    )
+
+    # ---- lifecycle hooks -------------------------------------------------
+
+    def on_post_build(self, config, **kwargs):
+        """Real MkDocs post-build hook: crawl the built site and copy assets."""
+        if not self.config["enabled"]:
+            return
+
+        site_dir = config["site_dir"]
+        project_dir = _project_dir(config)
+        output_abs = os.path.join(site_dir, self.config["output_dir"])
+        base_url = self._resolve_base_url(config)
+
+        # 1. Build the index by shelling out to the Node CLI. Real flags,
+        #    confirmed against bin/rangefind.js:
+        #      rangefind build <dir> --output <dir> --base-url <url>
+        command = [
+            self.config["node_command"],
+            "rangefind",
+            "build",
+            site_dir,
+            "--output",
+            output_abs,
+            "--base-url",
+            base_url,
+        ]
+        log.info("Building Rangefind index: %s", " ".join(command))
+        try:
+            result = subprocess.run(
+                command,
+                cwd=project_dir,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise PluginError(
+                f"mkdocs-rangefind: could not run '{self.config['node_command']}'. "
+                "Node.js and the `rangefind` npm package must be installed and on "
+                f"PATH. Original error: {exc}"
+            )
+        if result.returncode != 0:
+            raise PluginError(
+                "mkdocs-rangefind: `rangefind build` failed "
+                f"(exit code {result.returncode}).\n"
+                f"command: {' '.join(command)}\n"
+                f"stdout:\n{result.stdout}\n"
+                f"stderr:\n{result.stderr}"
+            )
+        if result.stdout.strip():
+            log.info(result.stdout.strip())
+
+        # 2. Copy the Web Component assets into the site.
+        js_src, css_src = self._resolve_assets(project_dir)
+        assets_abs = os.path.join(site_dir, self.config["assets_dir"])
+        os.makedirs(assets_abs, exist_ok=True)
+        shutil.copyfile(js_src, os.path.join(assets_abs, "rangefind-search.js"))
+        if self.config["theme"]:
+            shutil.copyfile(css_src, os.path.join(assets_abs, "rangefind-search.css"))
+        log.info("Copied Rangefind widget assets to %s", assets_abs)
+
+    def on_post_page(self, output, page, config, **kwargs):
+        """Real MkDocs post-page hook: inject the widget into the page HTML."""
+        if not self.config["enabled"]:
+            return output
+
+        assets_dir = self.config["assets_dir"].strip("/")
+        output_dir = self.config["output_dir"].strip("/")
+        page_url = page.url
+
+        js_href = get_relative_url(f"{assets_dir}/rangefind-search.js", page_url)
+        index_src = get_relative_url(f"{output_dir}/", page_url)
+
+        head_injection = f'<script type="module" src="{_attr(js_href)}"></script>'
+        if self.config["theme"]:
+            css_href = get_relative_url(f"{assets_dir}/rangefind-search.css", page_url)
+            head_injection = (
+                f'<link rel="stylesheet" href="{_attr(css_href)}">\n' + head_injection
+            )
+        output = _inject_head(output, head_injection)
+
+        if self.config["placement"] != "manual":
+            element = self._render_element(index_src)
+            output = self._inject_element(output, element)
+
+        return output
+
+    # ---- helpers ---------------------------------------------------------
+
+    def _resolve_base_url(self, config):
+        configured = self.config["base_url"].strip()
+        if configured:
+            return configured
+        site_url = config.get("site_url")
+        if site_url:
+            path = urlsplit(site_url).path or "/"
+            return path if path.endswith("/") else path + "/"
+        return "/"
+
+    def _render_element(self, index_src):
+        attrs = {"src": index_src, "placeholder": self.config["placeholder"]}
+        for key, value in (self.config["element_attributes"] or {}).items():
+            if value is True:
+                attrs[str(key)] = ""  # bare boolean attribute
+            elif value is False or value is None:
+                continue
+            else:
+                attrs[str(key)] = str(value)
+        rendered = []
+        for key, value in attrs.items():
+            rendered.append(key if value == "" else f'{key}="{_attr(value)}"')
+        return f"<rangefind-search {' '.join(rendered)}></rangefind-search>"
+
+    def _inject_element(self, output, element):
+        selector = self.config["selector"]
+        if selector:
+            idx = output.find(selector)
+            if idx != -1:
+                cut = idx + len(selector)
+                return output[:cut] + "\n" + element + output[cut:]
+            log.warning(
+                "mkdocs-rangefind: selector %r not found on a page; "
+                "falling back to placement before </body>.",
+                selector,
+            )
+        return _inject_body_end(output, element)
+
+    def _resolve_assets(self, project_dir):
+        """Locate the component's JS/CSS.
+
+        Preference order:
+          1. Explicit `element_js_path` / `element_css_path` config values.
+          2. Ask Node to resolve them via the `rangefind` package export map
+             (`rangefind/element` and `rangefind/element.css`). The export map
+             is the robust seam here: `require.resolve('rangefind/package.json')`
+             is blocked by the package's `exports`, but the declared subpath
+             exports point straight at dist/rangefind-search.{js,css}.
+        """
+        js_cfg = self.config["element_js_path"].strip()
+        css_cfg = self.config["element_css_path"].strip()
+        if js_cfg and css_cfg:
+            return _require_file(js_cfg, project_dir), _require_file(css_cfg, project_dir)
+
+        node_bin = _node_binary(self.config["node_command"])
+        js = js_cfg or self._node_resolve(node_bin, "rangefind/element", project_dir)
+        css = css_cfg or self._node_resolve(node_bin, "rangefind/element.css", project_dir)
+        return _require_file(js, project_dir), _require_file(css, project_dir)
+
+    def _node_resolve(self, node_bin, specifier, project_dir):
+        code = f"process.stdout.write(require.resolve({specifier!r}))"
+        try:
+            result = subprocess.run(
+                [node_bin, "-e", code],
+                cwd=project_dir,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise PluginError(
+                f"mkdocs-rangefind: could not run Node ('{node_bin}') to resolve "
+                f"the '{specifier}' asset. Install Node.js, or set "
+                "`element_js_path`/`element_css_path` explicitly in mkdocs.yml. "
+                f"Original error: {exc}"
+            )
+        path = result.stdout.strip()
+        if result.returncode != 0 or not path:
+            raise PluginError(
+                f"mkdocs-rangefind: could not resolve '{specifier}' from the "
+                f"`rangefind` npm package (run from {project_dir}). Make sure "
+                "`rangefind` is installed there (e.g. `npm install rangefind`), "
+                "or set `element_js_path`/`element_css_path` in mkdocs.yml.\n"
+                f"stderr:\n{result.stderr}"
+            )
+        return path
+
+
+# ---- module-level pure helpers ------------------------------------------
+
+
+def _project_dir(config):
+    config_file = config.get("config_file_path")
+    if config_file:
+        return os.path.dirname(os.path.abspath(config_file))
+    return os.getcwd()
+
+
+def _node_binary(node_command):
+    """Derive a plain Node binary from the configured command.
+
+    The index is built with `node_command` (default "npx"), but resolving the
+    asset paths needs Node itself. If the command is npx, use the sibling
+    `node`; otherwise assume the command can already run `-e`.
+    """
+    base = os.path.basename(node_command)
+    if base in ("npx", "npx.cmd", "npx.exe"):
+        directory = os.path.dirname(node_command)
+        return os.path.join(directory, "node") if directory else "node"
+    return node_command
+
+
+def _require_file(path, project_dir):
+    resolved = path if os.path.isabs(path) else os.path.join(project_dir, path)
+    if not os.path.isfile(resolved):
+        raise PluginError(f"mkdocs-rangefind: asset file not found: {resolved}")
+    return resolved
+
+
+def _attr(value):
+    return str(value).replace("&", "&amp;").replace('"', "&quot;")
+
+
+def _inject_head(output, snippet):
+    lower = output.lower()
+    idx = lower.rfind("</head>")
+    if idx != -1:
+        return output[:idx] + snippet + "\n" + output[idx:]
+    return _inject_body_end(output, snippet)
+
+
+def _inject_body_end(output, snippet):
+    lower = output.lower()
+    idx = lower.rfind("</body>")
+    if idx != -1:
+        return output[:idx] + snippet + "\n" + output[idx:]
+    return output + "\n" + snippet

mkdocs_rangefind-0.1.0/test/fixture/docs/about.md

@@ -0,0 +1,6 @@
+# About
+
+About page distinct content xylophone marker.
+
+The rare word above (xylophone) makes this page uniquely findable so the search
+verification can prove the index actually resolves a query to this document.

mkdocs_rangefind-0.1.0/test/fixture/docs/index.md

@@ -0,0 +1,6 @@
+# Home
+
+MkDocs fixture home content for search testing.
+
+This is the landing page of a minimal MkDocs site used to exercise the
+mkdocs-rangefind plugin end to end.

mkdocs_rangefind-0.1.0/test/fixture/mkdocs.yml

@@ -0,0 +1,11 @@
+site_name: Rangefind MkDocs Fixture
+site_url: https://example.com/
+docs_dir: docs
+site_dir: site
+
+plugins:
+  - rangefind:
+      # Point the CLI at the local repo checkout via the node_modules symlink
+      # the test creates, so the build works offline in CI.
+      node_command: npx
+      theme: true

mkdocs_rangefind-0.1.0/test/test_build.py

@@ -0,0 +1,121 @@
+"""End-to-end test for the mkdocs-rangefind plugin.
+
+Runs a real `mkdocs build` against a fixture site, then asserts that the
+Rangefind index and widget assets were produced and the widget tags injected.
+Finally it runs a companion Node script that serves the built site over a
+Range-capable HTTP server and queries the real runtime, proving the index is
+searchable.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+FIXTURE = os.path.join(HERE, "fixture")
+# integrations/mkdocs-rangefind/test -> repo root is three levels up.
+REPO_ROOT = os.path.abspath(os.path.join(HERE, "..", "..", ".."))
+SITE_DIR = os.path.join(FIXTURE, "site")
+
+
+def _link(target, link_path):
+    if os.path.islink(link_path) or os.path.exists(link_path):
+        if os.path.islink(link_path):
+            os.unlink(link_path)
+        elif os.path.isdir(link_path):
+            shutil.rmtree(link_path)
+        else:
+            os.remove(link_path)
+    os.symlink(target, link_path)
+
+
+class RangefindMkDocsBuildTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        # Make the local repo checkout resolvable as the `rangefind` npm package
+        # from the fixture dir, so `npx rangefind` and Node's require.resolve
+        # work offline (mirrors what `npm install rangefind` would produce).
+        node_modules = os.path.join(FIXTURE, "node_modules")
+        os.makedirs(os.path.join(node_modules, ".bin"), exist_ok=True)
+        _link(REPO_ROOT, os.path.join(node_modules, "rangefind"))
+        _link(
+            os.path.join("..", "rangefind", "bin", "rangefind.js"),
+            os.path.join(node_modules, ".bin", "rangefind"),
+        )
+
+        if os.path.isdir(SITE_DIR):
+            shutil.rmtree(SITE_DIR)
+
+        # Run the real MkDocs build from within the venv.
+        result = subprocess.run(
+            [sys.executable, "-m", "mkdocs", "build", "--strict"],
+            cwd=FIXTURE,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        cls.build = result
+        if result.returncode != 0:
+            raise AssertionError(
+                "mkdocs build failed:\n"
+                f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+            )
+
+    def test_build_succeeded(self):
+        self.assertEqual(self.build.returncode, 0, self.build.stderr)
+
+    def test_manifest_exists_and_indexed_all_pages(self):
+        manifest_path = os.path.join(SITE_DIR, "rangefind", "manifest.min.json")
+        self.assertTrue(os.path.isfile(manifest_path), manifest_path)
+        with open(manifest_path, encoding="utf-8") as handle:
+            manifest = json.load(handle)
+        self.assertGreaterEqual(
+            manifest.get("total", 0), 2, f"expected >=2 docs, manifest={manifest!r}"
+        )
+
+    def test_widget_assets_copied(self):
+        assets = os.path.join(SITE_DIR, "_rangefind")
+        self.assertTrue(os.path.isfile(os.path.join(assets, "rangefind-search.js")))
+        self.assertTrue(os.path.isfile(os.path.join(assets, "rangefind-search.css")))
+
+    def test_page_html_has_injected_tags(self):
+        index_html = os.path.join(SITE_DIR, "index.html")
+        with open(index_html, encoding="utf-8") as handle:
+            html = handle.read()
+        self.assertIn('<script type="module"', html)
+        self.assertIn("rangefind-search.js", html)
+        self.assertIn("<rangefind-search", html)
+        # theme: true in the fixture -> stylesheet link injected too.
+        self.assertIn("rangefind-search.css", html)
+
+    def test_nested_relative_paths(self):
+        # The About page lives at site/about/index.html (use_directory_urls),
+        # so its asset references must be one level up.
+        about_html = os.path.join(SITE_DIR, "about", "index.html")
+        with open(about_html, encoding="utf-8") as handle:
+            html = handle.read()
+        self.assertIn("../_rangefind/rangefind-search.js", html)
+        self.assertIn('src="../rangefind/"', html)
+
+    def test_index_is_searchable(self):
+        script = os.path.join(HERE, "verify_search.mjs")
+        result = subprocess.run(
+            ["node", script, SITE_DIR, "rangefind", "xylophone"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        self.assertEqual(
+            result.returncode,
+            0,
+            f"search verification failed:\nstdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}",
+        )
+        self.assertIn("resolved to the About page", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

mkdocs_rangefind-0.1.0/test/verify_search.mjs

@@ -0,0 +1,90 @@
+// Proves the Rangefind index produced by the MkDocs plugin is actually
+// searchable through the real range-request runtime (not merely present on
+// disk). Serves the built site with a Range-capable static server (mirroring
+// the serveStatic helper in the repo's test/build-runtime.test.js), then runs a
+// real query and asserts the expected document comes back.
+//
+// Usage: node verify_search.mjs <site_dir> [outputDir] [query]
+
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+// Resolve the runtime from the monorepo checkout (this file lives at
+// integrations/mkdocs-rangefind/test/, so the repo root is three levels up).
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..", "..", "..");
+const { createSearch } = await import(resolve(repoRoot, "src", "runtime.js"));
+
+const siteDir = process.argv[2];
+const outputDir = process.argv[3] || "rangefind";
+const query = process.argv[4] || "xylophone";
+if (!siteDir) {
+  console.error("verify_search.mjs: missing <site_dir> argument");
+  process.exit(2);
+}
+
+async function serveStatic(root) {
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url, "http://localhost");
+      const path = resolve(root, `.${decodeURIComponent(url.pathname)}`);
+      if (!path.startsWith(resolve(root))) {
+        response.writeHead(403).end();
+        return;
+      }
+      const data = await readFile(path);
+      const range = request.headers.range?.match(/^bytes=(\d+)-(\d+)$/);
+      if (range) {
+        const start = Number(range[1]);
+        const end = Math.min(Number(range[2]), data.length - 1);
+        response.writeHead(206, {
+          "Accept-Ranges": "bytes",
+          "Content-Length": String(end - start + 1),
+          "Content-Range": `bytes ${start}-${end}/${data.length}`
+        });
+        response.end(data.subarray(start, end + 1));
+        return;
+      }
+      response.writeHead(200, { "Content-Length": String(data.length) });
+      response.end(data);
+    } catch {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise(res => server.listen(0, "127.0.0.1", res));
+  const { port } = server.address();
+  return {
+    baseUrl: `http://127.0.0.1:${port}/${outputDir}/`,
+    close: () => new Promise(res => server.close(res))
+  };
+}
+
+const server = await serveStatic(siteDir);
+try {
+  const engine = await createSearch({ baseUrl: server.baseUrl });
+  const response = await engine.search({ q: query, size: 5 });
+  const results = response.results || [];
+  console.log(
+    `query=${JSON.stringify(query)} -> ${results.length} result(s):`,
+    results.map(r => ({ id: r.id, title: r.title, url: r.url }))
+  );
+  assert.ok(results.length >= 1, `expected at least one result for "${query}"`);
+  const match = results.find(
+    r =>
+      (r.url && r.url.toLowerCase().includes("about")) ||
+      (r.id && r.id.toLowerCase().includes("about")) ||
+      (r.title && r.title.toLowerCase().includes("about"))
+  );
+  assert.ok(
+    match,
+    `expected the About page in results for "${query}", got ${JSON.stringify(
+      results.map(r => r.url || r.id)
+    )}`
+  );
+  console.log(`OK: "${query}" resolved to the About page (${match.url || match.id}).`);
+} finally {
+  await server.close();
+}