Metadata-Version: 2.4
Name: mkdocs-beacon-search
Version: 0.1.2
Summary: MkDocs plugin for the Beacon search widget
Project-URL: Homepage, https://github.com/Mirantis/beacon-mkdocs-plugin
Project-URL: Repository, https://github.com/Mirantis/beacon-mkdocs-plugin
Project-URL: Issues, https://github.com/Mirantis/beacon-mkdocs-plugin/issues
Project-URL: Changelog, https://github.com/Mirantis/beacon-mkdocs-plugin/blob/main/CHANGELOG.md
Author: Mirantis, Inc.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: beacon,mkdocs,mkdocs-plugin,search
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: mkdocs>=1.6
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-beautifulsoup4; extra == 'dev'
Description-Content-Type: text/markdown

# beacon-mkdocs-plugin

MkDocs plugin that embeds the [Beacon](https://github.com/Mirantis) search widget into your documentation site.

## Status

Pre-alpha. Not yet published to PyPI.

## Install

Once released:

```bash
pip install mkdocs-beacon-search
```

## Quick start

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

```yaml
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:

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

```yaml
# 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:

```html
<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](CONTRIBUTING.md).

## License

Apache-2.0 — see [LICENSE](LICENSE).

## Contributing

Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
