mkdocs-beacon-search 0.1.0

MkDocs plugin for the Beacon search widget

beacon-mkdocs-plugin

MkDocs plugin that embeds the Beacon search widget into your documentation site.

Status

Pre-alpha. Not yet published to PyPI.

Install

Once released:

pip install mkdocs-beacon-search

Quick start

Add the plugin to your mkdocs.yml and point it at a Beacon API:

plugins:
  - beacon-search:
      api_url: https://search-api.example.com
      product: k0s

Run mkdocs build (or mkdocs serve locally). The plugin copies the widget bundle into the built site and mounts <beacon-search> into your theme automatically.

Configuration reference

Option	Type	Default	Description
api_url	URL	— (required)	Base URL of the Beacon search API.
product	string	(unset)	Scope search to a single product. Maps to the widget's product attribute.
embed_id	string	(unset)	Publisher-supplied identifier for analytics segmentation (e.g. footer-v1.31).
analytics	on | off	on	Widget analytics posture. off fully opts the widget out (no script load, no events).
analytics_consent_required	bool	false	When true, the widget defers analytics events until the host CMP dispatches beacon-analytics-consent-granted on document.
replace_search	bool	true	On Material for MkDocs, replace the theme's built-in .md-search block with the widget. Set to false to keep both.
placement	CSS selector	(theme default)	Override where the widget is mounted. When set, the plugin appends <beacon-search> inside the first matching element on every page.
enabled	bool	true	Plugin master switch. Supports MkDocs' !ENV syntax for environment-gated builds.

Unknown keys are rejected. Missing api_url fails the build.

Theme compatibility

Theme	Default placement	Notes
material (Material for MkDocs)	Replaces .md-search when replace_search: true; otherwise appends to .md-header__inner.	Primary target. Tested against Material 9.x.
mkdocs (MkDocs built-in)	Appends to .navbar.	Works out of the box.
readthedocs (MkDocs built-in RTD theme)	Appends to .wy-side-nav-search (or .wy-nav-top if absent).	Best-effort.
Anything else	No auto-placement.	Set placement: to a CSS selector, or use the Jinja macro.

Manual placement (Jinja macro)

For full control, the plugin registers a {{ beacon_search() }} Jinja function. Use it inside a theme template override:

{# overrides/main.html #}
{% extends "base.html" %}
{% block content %}
  {{ beacon_search() }}
  {{ super() }}
{% endblock %}

# mkdocs.yml
theme:
  name: mkdocs
  custom_dir: overrides

When a page already contains a <beacon-search> element (from the macro or from markdown), auto-placement skips that page — no double-mount.

Content Security Policy

The widget is a pure <script> + custom element. If your site enforces CSP and you want widget analytics enabled:

• script-src must allow https://www.googletagmanager.com
• connect-src must allow https://www.google-analytics.com and https://*.analytics.google.com

If you set analytics: off, no third-party domains are contacted.

Migration from the <script> + custom element integration

If your site currently embeds the widget directly:

<script src="https://.../beacon-search.umd.js"></script>
<beacon-search api-url="..." product="k0s"></beacon-search>

Remove those two lines and add the plugin to mkdocs.yml. The plugin takes over script loading and element placement.

Development

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.

Contributing

Pull requests are welcome. See CONTRIBUTING.md for development setup.