mkdocs-ai-chatbot 1.0.0__tar.gz

mkdocs_ai_chatbot-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asyntai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_ai_chatbot-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: mkdocs-ai-chatbot
+Version: 1.0.0
+Summary: Add the Asyntai AI chat assistant to your MkDocs site. It answers visitor questions from your own documentation.
+Author-email: Asyntai <hello@asyntai.com>
+License-Expression: MIT
+Project-URL: Homepage, https://asyntai.com/documentation/integrations/mkdocs/
+Project-URL: Documentation, https://asyntai.com/documentation/integrations/mkdocs/
+Project-URL: Source, https://github.com/asyntai/mkdocs-ai-chatbot
+Project-URL: Issues, https://github.com/asyntai/mkdocs-ai-chatbot/issues
+Keywords: mkdocs,mkdocs-plugin,chatbot,ai,chat,support,documentation,asyntai
+Classifier: Framework :: MkDocs
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4
+Dynamic: license-file
+
+# mkdocs-ai-chatbot
+
+Add the [Asyntai](https://asyntai.com) AI chat assistant to your MkDocs site.
+It answers visitor questions from your own documentation, day and night.
+
+Works with every MkDocs theme, including Material for MkDocs and Read the Docs.
+
+## Install
+
+```bash
+pip install mkdocs-ai-chatbot
+```
+
+Then add the plugin in `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - asyntai:
+      widget_id: asyntai_1a2b3c4d5e6f
+```
+
+Build the site. The chat bubble is on every page.
+
+Keep `search` in the list if you use it. When `mkdocs.yml` has a `plugins`
+section, MkDocs only loads the plugins named there.
+
+## Where the widget ID comes from
+
+Open the Install page in your [Asyntai dashboard](https://asyntai.com/dashboard).
+The widget ID is the value of `data-asyntai-id` in the snippet shown there. It
+starts with `asyntai_`.
+
+Creating an account is free, and the Free plan is enough to try the widget.
+
+## Options
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `widget_id` | string | required | Your Asyntai widget ID |
+| `enable_on_serve` | boolean | `true` | Set to `false` to keep the widget off the site during `mkdocs serve` |
+| `script_url` | string | the Asyntai CDN | Advanced. Load the widget from another URL |
+
+A missing or malformed `widget_id` stops the build with a message that says how
+to fix it.
+
+## What the plugin does
+
+- It adds one `<script>` tag in front of the closing body tag of every page.
+- It marks the tag `async`, so your documentation renders first.
+- It changes nothing else. No theme files are overridden and no CSS is added.
+- If a page already has the Asyntai snippet, for example from a theme
+  override, the plugin leaves that page alone.
+
+## Answering from your documentation
+
+Asyntai reads your published pages. Add your site URL in the dashboard, and the
+assistant answers from the same documentation the widget sits on. You can also
+add documents, and question and answer pairs.
+
+## Removing it
+
+Delete the `asyntai` entry from `mkdocs.yml` and build again. The widget is
+gone.
+
+## Support
+
+Email [hello@asyntai.com](mailto:hello@asyntai.com), or read the
+[MkDocs guide](https://asyntai.com/documentation/integrations/mkdocs/).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

mkdocs_ai_chatbot-1.0.0/README.md

@@ -0,0 +1,73 @@
+# mkdocs-ai-chatbot
+
+Add the [Asyntai](https://asyntai.com) AI chat assistant to your MkDocs site.
+It answers visitor questions from your own documentation, day and night.
+
+Works with every MkDocs theme, including Material for MkDocs and Read the Docs.
+
+## Install
+
+```bash
+pip install mkdocs-ai-chatbot
+```
+
+Then add the plugin in `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - asyntai:
+      widget_id: asyntai_1a2b3c4d5e6f
+```
+
+Build the site. The chat bubble is on every page.
+
+Keep `search` in the list if you use it. When `mkdocs.yml` has a `plugins`
+section, MkDocs only loads the plugins named there.
+
+## Where the widget ID comes from
+
+Open the Install page in your [Asyntai dashboard](https://asyntai.com/dashboard).
+The widget ID is the value of `data-asyntai-id` in the snippet shown there. It
+starts with `asyntai_`.
+
+Creating an account is free, and the Free plan is enough to try the widget.
+
+## Options
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `widget_id` | string | required | Your Asyntai widget ID |
+| `enable_on_serve` | boolean | `true` | Set to `false` to keep the widget off the site during `mkdocs serve` |
+| `script_url` | string | the Asyntai CDN | Advanced. Load the widget from another URL |
+
+A missing or malformed `widget_id` stops the build with a message that says how
+to fix it.
+
+## What the plugin does
+
+- It adds one `<script>` tag in front of the closing body tag of every page.
+- It marks the tag `async`, so your documentation renders first.
+- It changes nothing else. No theme files are overridden and no CSS is added.
+- If a page already has the Asyntai snippet, for example from a theme
+  override, the plugin leaves that page alone.
+
+## Answering from your documentation
+
+Asyntai reads your published pages. Add your site URL in the dashboard, and the
+assistant answers from the same documentation the widget sits on. You can also
+add documents, and question and answer pairs.
+
+## Removing it
+
+Delete the `asyntai` entry from `mkdocs.yml` and build again. The widget is
+gone.
+
+## Support
+
+Email [hello@asyntai.com](mailto:hello@asyntai.com), or read the
+[MkDocs guide](https://asyntai.com/documentation/integrations/mkdocs/).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot/__init__.py

@@ -0,0 +1,4 @@
+from .plugin import AsyntaiPlugin, DEFAULT_SCRIPT_URL
+
+__all__ = ["AsyntaiPlugin", "DEFAULT_SCRIPT_URL"]
+__version__ = "1.0.0"

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot/plugin.py

@@ -0,0 +1,102 @@
+"""
+Asyntai AI chatbot for MkDocs.
+
+Adds the Asyntai chat widget to every page that MkDocs builds. The plugin
+writes the ordinary embed snippet in front of the closing body tag of each
+page. Nothing else about the site changes: no theme files are overridden and
+no CSS is added.
+"""
+
+import re
+
+from mkdocs.config import config_options
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin
+
+DEFAULT_SCRIPT_URL = "https://widget.asyntai.com/static/js/chat-widget.js"
+WIDGET_ID_PATTERN = re.compile(r"^asyntai_[A-Za-z0-9]+$")
+
+# The last closing body tag of the page. A page can quote "</body>" inside a
+# code block, so only the final one is the real end of the document.
+_BODY_END = re.compile(r"</body\s*>", re.IGNORECASE)
+
+
+def build_tag(widget_id, script_url):
+    return (
+        '<script async src="{src}" data-asyntai-id="{wid}"></script>'.format(
+            src=script_url.replace('"', "&quot;"),
+            wid=widget_id,
+        )
+    )
+
+
+def insert_tag(html, tag):
+    """Put the tag in front of the last </body>, or at the end if there is none."""
+    matches = list(_BODY_END.finditer(html))
+    if not matches:
+        return html + tag
+    end = matches[-1].start()
+    return html[:end] + tag + "\n" + html[end:]
+
+
+class AsyntaiPlugin(BasePlugin):
+    config_scheme = (
+        ("widget_id", config_options.Type(str, default="")),
+        # Set to false to keep the widget off the site during `mkdocs serve`.
+        ("enable_on_serve", config_options.Type(bool, default=True)),
+        # Advanced. Load the widget from another URL.
+        ("script_url", config_options.Type(str, default=DEFAULT_SCRIPT_URL)),
+    )
+
+    def __init__(self):
+        super().__init__()
+        self._command = "build"
+        self._tag = ""
+
+    def on_startup(self, *, command, dirty):
+        self._command = command
+
+    def on_config(self, config):
+        widget_id = (self.config.get("widget_id") or "").strip()
+        if not widget_id:
+            raise PluginError(
+                'mkdocs-ai-chatbot: "widget_id" is required. Copy it from the '
+                "Install page of your Asyntai dashboard, for example "
+                "asyntai_1a2b3c4d5e6f."
+            )
+        if not WIDGET_ID_PATTERN.match(widget_id):
+            raise PluginError(
+                'mkdocs-ai-chatbot: "{0}" does not look like a widget ID. It '
+                "starts with asyntai_, for example asyntai_1a2b3c4d5e6f.".format(
+                    widget_id
+                )
+            )
+        script_url = (self.config.get("script_url") or "").strip() or DEFAULT_SCRIPT_URL
+        self._tag = build_tag(widget_id, script_url)
+        return config
+
+    def _active(self):
+        if self._command == "serve" and not self.config.get("enable_on_serve"):
+            return False
+        return bool(self._tag)
+
+    def _add(self, html):
+        if not self._active():
+            return html
+        # The site owner already pasted the snippet in a theme override. Two
+        # loaders would only fight over one chat bubble, so keep theirs.
+        if "data-asyntai-id" in html:
+            return html
+        return insert_tag(html, self._tag)
+
+    def on_post_page(self, output, *, page, config):
+        return self._add(output)
+
+    def on_post_template(self, output_content, *, template_name, config):
+        # Static templates such as 404.html, and search.html in the Read the
+        # Docs theme, are not pages, so on_post_page never sees them. A
+        # visitor on a dead link or a failed search needs the chat most.
+        # sitemap.xml and other non-HTML templates stay as they are.
+        if template_name.lower().endswith((".html", ".htm")):
+            return self._add(output_content)
+        return output_content

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: mkdocs-ai-chatbot
+Version: 1.0.0
+Summary: Add the Asyntai AI chat assistant to your MkDocs site. It answers visitor questions from your own documentation.
+Author-email: Asyntai <hello@asyntai.com>
+License-Expression: MIT
+Project-URL: Homepage, https://asyntai.com/documentation/integrations/mkdocs/
+Project-URL: Documentation, https://asyntai.com/documentation/integrations/mkdocs/
+Project-URL: Source, https://github.com/asyntai/mkdocs-ai-chatbot
+Project-URL: Issues, https://github.com/asyntai/mkdocs-ai-chatbot/issues
+Keywords: mkdocs,mkdocs-plugin,chatbot,ai,chat,support,documentation,asyntai
+Classifier: Framework :: MkDocs
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4
+Dynamic: license-file
+
+# mkdocs-ai-chatbot
+
+Add the [Asyntai](https://asyntai.com) AI chat assistant to your MkDocs site.
+It answers visitor questions from your own documentation, day and night.
+
+Works with every MkDocs theme, including Material for MkDocs and Read the Docs.
+
+## Install
+
+```bash
+pip install mkdocs-ai-chatbot
+```
+
+Then add the plugin in `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - asyntai:
+      widget_id: asyntai_1a2b3c4d5e6f
+```
+
+Build the site. The chat bubble is on every page.
+
+Keep `search` in the list if you use it. When `mkdocs.yml` has a `plugins`
+section, MkDocs only loads the plugins named there.
+
+## Where the widget ID comes from
+
+Open the Install page in your [Asyntai dashboard](https://asyntai.com/dashboard).
+The widget ID is the value of `data-asyntai-id` in the snippet shown there. It
+starts with `asyntai_`.
+
+Creating an account is free, and the Free plan is enough to try the widget.
+
+## Options
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `widget_id` | string | required | Your Asyntai widget ID |
+| `enable_on_serve` | boolean | `true` | Set to `false` to keep the widget off the site during `mkdocs serve` |
+| `script_url` | string | the Asyntai CDN | Advanced. Load the widget from another URL |
+
+A missing or malformed `widget_id` stops the build with a message that says how
+to fix it.
+
+## What the plugin does
+
+- It adds one `<script>` tag in front of the closing body tag of every page.
+- It marks the tag `async`, so your documentation renders first.
+- It changes nothing else. No theme files are overridden and no CSS is added.
+- If a page already has the Asyntai snippet, for example from a theme
+  override, the plugin leaves that page alone.
+
+## Answering from your documentation
+
+Asyntai reads your published pages. Add your site URL in the dashboard, and the
+assistant answers from the same documentation the widget sits on. You can also
+add documents, and question and answer pairs.
+
+## Removing it
+
+Delete the `asyntai` entry from `mkdocs.yml` and build again. The widget is
+gone.
+
+## Support
+
+Email [hello@asyntai.com](mailto:hello@asyntai.com), or read the
+[MkDocs guide](https://asyntai.com/documentation/integrations/mkdocs/).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+mkdocs_ai_chatbot/__init__.py
+mkdocs_ai_chatbot/plugin.py
+mkdocs_ai_chatbot.egg-info/PKG-INFO
+mkdocs_ai_chatbot.egg-info/SOURCES.txt
+mkdocs_ai_chatbot.egg-info/dependency_links.txt
+mkdocs_ai_chatbot.egg-info/entry_points.txt
+mkdocs_ai_chatbot.egg-info/requires.txt
+mkdocs_ai_chatbot.egg-info/top_level.txt
+tests/test_plugin.py

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+asyntai = mkdocs_ai_chatbot.plugin:AsyntaiPlugin

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/requires.txt

@@ -0,0 +1 @@
+mkdocs>=1.4

mkdocs_ai_chatbot-1.0.0/mkdocs_ai_chatbot.egg-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_ai_chatbot

mkdocs_ai_chatbot-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mkdocs-ai-chatbot"
+version = "1.0.0"
+description = "Add the Asyntai AI chat assistant to your MkDocs site. It answers visitor questions from your own documentation."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Asyntai", email = "hello@asyntai.com"}]
+requires-python = ">=3.8"
+dependencies = ["mkdocs>=1.4"]
+keywords = ["mkdocs", "mkdocs-plugin", "chatbot", "ai", "chat", "support", "documentation", "asyntai"]
+classifiers = [
+    "Framework :: MkDocs",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation",
+    "Topic :: Communications :: Chat",
+]
+
+[project.urls]
+Homepage = "https://asyntai.com/documentation/integrations/mkdocs/"
+Documentation = "https://asyntai.com/documentation/integrations/mkdocs/"
+Source = "https://github.com/asyntai/mkdocs-ai-chatbot"
+Issues = "https://github.com/asyntai/mkdocs-ai-chatbot/issues"
+
+[project.entry-points."mkdocs.plugins"]
+asyntai = "mkdocs_ai_chatbot.plugin:AsyntaiPlugin"
+
+[tool.setuptools]
+packages = ["mkdocs_ai_chatbot"]

mkdocs_ai_chatbot-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mkdocs_ai_chatbot-1.0.0/tests/test_plugin.py

@@ -0,0 +1,379 @@
+"""
+Tests for mkdocs-ai-chatbot.
+
+Most checks run a real `mkdocs build` (and one real `mkdocs serve`) on small
+sites made in a temporary folder, so they test what a user gets, not a mock.
+Needs mkdocs and the plugin installed in the same Python; Material for MkDocs
+is used when it is installed.
+
+Run: python plugins/mkdocs/tests/test_plugin.py
+"""
+
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+
+from mkdocs_ai_chatbot.plugin import (  # noqa: E402
+    DEFAULT_SCRIPT_URL,
+    AsyntaiPlugin,
+    insert_tag,
+)
+
+WIDGET_ID = "asyntai_1a2b3c4d5e6f"
+TAG_RE = re.compile(r"<script[^>]*data-asyntai-id=\"([^\"]+)\"[^>]*></script>")
+
+passed = []
+failed = []
+
+
+def check(name, fn):
+    try:
+        fn()
+        passed.append(name)
+        print("  PASS  " + name)
+    except Exception as err:  # noqa: BLE001
+        failed.append(name)
+        print("  FAIL  " + name + "  -> " + repr(err))
+
+
+def has_material():
+    try:
+        import material  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def make_site(plugin_yaml, theme="mkdocs", extra_yaml="", pages=None, overrides=None):
+    root = tempfile.mkdtemp(prefix="mkdocs_asyntai_")
+    docs = os.path.join(root, "docs")
+    os.makedirs(docs)
+    pages = pages or {
+        "index.md": "# Home\n\nWelcome. Příliš žluťoučký kůň.\n",
+        "guide/setup.md": "# Setup\n\nInstall it.\n",
+    }
+    for rel, text in pages.items():
+        path = os.path.join(docs, rel)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(text)
+    theme_block = "theme:\n  name: {0}\n".format(theme)
+    if overrides:
+        over = os.path.join(root, "overrides")
+        os.makedirs(over)
+        for rel, text in overrides.items():
+            with open(os.path.join(over, rel), "w", encoding="utf-8") as f:
+                f.write(text)
+        theme_block += "  custom_dir: overrides\n"
+    with open(os.path.join(root, "mkdocs.yml"), "w", encoding="utf-8") as f:
+        f.write(
+            "site_name: Test Docs\nsite_url: https://docs.example.com/\n"
+            + theme_block
+            + extra_yaml
+            + "plugins:\n  - search\n"
+            + plugin_yaml
+        )
+    return root
+
+
+def build(root):
+    return subprocess.run(
+        [sys.executable, "-m", "mkdocs", "build", "--strict"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def html_files(root):
+    site = os.path.join(root, "site")
+    for dirpath, _, files in os.walk(site):
+        for name in files:
+            if name.endswith(".html"):
+                yield os.path.join(dirpath, name)
+
+
+def read(path):
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def assert_every_page_has_one_tag(root, widget_id=WIDGET_ID, script_url=DEFAULT_SCRIPT_URL):
+    files = list(html_files(root))
+    assert len(files) >= 3, "expected index, guide page and 404, got %d" % len(files)
+    for path in files:
+        html = read(path)
+        tags = TAG_RE.findall(html)
+        assert tags == [widget_id], "%s has tags %r" % (os.path.basename(path), tags)
+        tag = TAG_RE.search(html).group(0)
+        assert "async" in tag, "tag is not async"
+        assert 'src="%s"' % script_url in tag, "wrong src in " + tag
+        after = html[html.index(tag) + len(tag):]
+        assert re.match(r"\s*</body>", after, re.I), "tag is not right before </body>"
+    return files
+
+
+def run_theme(theme, extra_yaml=""):
+    root = make_site("  - asyntai:\n      widget_id: %s\n" % WIDGET_ID, theme=theme, extra_yaml=extra_yaml)
+    try:
+        result = build(root)
+        assert result.returncode == 0, result.stderr[-800:]
+        files = assert_every_page_has_one_tag(root)
+        assert any(f.endswith("404.html") for f in files), "no 404.html"
+        index = read(os.path.join(root, "site", "index.html"))
+        assert "Příliš žluťoučký kůň" in index, "non-ASCII text changed"
+        sitemap = os.path.join(root, "site", "sitemap.xml")
+        if os.path.exists(sitemap):
+            assert "asyntai" not in read(sitemap), "sitemap was touched"
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+# --- insert_tag, the only string surgery -----------------------------------
+
+def t_insert_last_body():
+    html = "<html><body><pre>&lt;/body&gt; </body></pre></body></html>"
+    out = insert_tag(html, "<X>")
+    assert out.endswith("<X>\n</body></html>"), out
+
+
+def t_insert_uppercase():
+    out = insert_tag("<HTML><BODY>a</BODY ></HTML>", "<X>")
+    assert out == "<HTML><BODY>a<X>\n</BODY ></HTML>", out
+
+
+def t_insert_no_body():
+    assert insert_tag("<p>fragment</p>", "<X>") == "<p>fragment</p><X>"
+
+
+# --- real builds -------------------------------------------------------------
+
+def t_theme_mkdocs():
+    run_theme("mkdocs")
+
+
+def t_theme_readthedocs():
+    run_theme("readthedocs")
+
+
+def t_theme_material():
+    if not has_material():
+        raise RuntimeError("mkdocs-material is not installed")
+    run_theme("material")
+
+
+def t_theme_material_instant():
+    if not has_material():
+        raise RuntimeError("mkdocs-material is not installed")
+    root = make_site(
+        "  - asyntai:\n      widget_id: %s\n" % WIDGET_ID,
+        theme="material\n  features:\n    - navigation.instant",
+    )
+    try:
+        result = build(root)
+        assert result.returncode == 0, result.stderr[-800:]
+        assert_every_page_has_one_tag(root)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def expect_failure(plugin_yaml, needle):
+    root = make_site(plugin_yaml)
+    try:
+        result = build(root)
+        assert result.returncode != 0, "build passed but should fail"
+        out = result.stdout + result.stderr
+        assert needle in out, "message not shown, got: " + out[-600:]
+        assert not os.path.exists(os.path.join(root, "site", "index.html")), "site was written"
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_missing_id():
+    expect_failure("  - asyntai\n", '"widget_id" is required')
+
+
+def t_empty_id():
+    expect_failure("  - asyntai:\n      widget_id: '   '\n", '"widget_id" is required')
+
+
+def t_bad_id():
+    expect_failure("  - asyntai:\n      widget_id: 1a2b3c\n", "does not look like a widget ID")
+
+
+def t_wrong_type():
+    expect_failure("  - asyntai:\n      widget_id: [a, b]\n", "widget_id")
+
+
+def t_trimmed_id():
+    root = make_site("  - asyntai:\n      widget_id: '  %s  '\n" % WIDGET_ID)
+    try:
+        assert build(root).returncode == 0
+        assert_every_page_has_one_tag(root)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_custom_script_url():
+    url = "https://cdn.example.com/w.js"
+    root = make_site("  - asyntai:\n      widget_id: %s\n      script_url: %s\n" % (WIDGET_ID, url))
+    try:
+        assert build(root).returncode == 0
+        assert_every_page_has_one_tag(root, script_url=url)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_existing_snippet_kept():
+    main = (
+        '{% extends "base.html" %}\n{% block scripts %}{{ super() }}'
+        '<script async src="https://widget.asyntai.com/static/js/chat-widget.js" '
+        'data-asyntai-id="asyntai_ownsnippet1"></script>{% endblock %}\n'
+    )
+    root = make_site(
+        "  - asyntai:\n      widget_id: %s\n" % WIDGET_ID,
+        overrides={"main.html": main},
+    )
+    try:
+        assert build(root).returncode == 0
+        index = read(os.path.join(root, "site", "index.html"))
+        assert TAG_RE.findall(index) == ["asyntai_ownsnippet1"], TAG_RE.findall(index)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_body_in_code_block():
+    pages = {
+        "index.md": "# Home\n\n```html\n<html><body>x</body></html>\n```\n",
+        "guide/setup.md": "# Setup\n",
+    }
+    root = make_site("  - asyntai:\n      widget_id: %s\n" % WIDGET_ID, pages=pages)
+    try:
+        assert build(root).returncode == 0
+        assert_every_page_has_one_tag(root)
+        index = read(os.path.join(root, "site", "index.html"))
+        assert index.count("&lt;/body&gt;") == 1, "code block changed"
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_no_plugin_no_tag():
+    root = make_site("")
+    try:
+        assert build(root).returncode == 0
+        for path in html_files(root):
+            assert "data-asyntai-id" not in read(path)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+# --- serve -------------------------------------------------------------------
+
+def free_port():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def serve_and_fetch(plugin_yaml):
+    root = make_site(plugin_yaml)
+    port = free_port()
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "mkdocs", "serve", "-a", "127.0.0.1:%d" % port, "--no-livereload"],
+        cwd=root,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    try:
+        deadline = time.time() + 30
+        while True:
+            try:
+                with urllib.request.urlopen("http://127.0.0.1:%d/guide/setup/" % port, timeout=2) as r:
+                    return r.read().decode("utf-8")
+            except Exception:  # noqa: BLE001
+                if time.time() > deadline:
+                    raise
+                time.sleep(0.5)
+    finally:
+        proc.terminate()
+        proc.wait(timeout=10)
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def t_serve_default_on():
+    html = serve_and_fetch("  - asyntai:\n      widget_id: %s\n" % WIDGET_ID)
+    assert TAG_RE.findall(html) == [WIDGET_ID], "serve page has no widget"
+
+
+def t_serve_off():
+    html = serve_and_fetch("  - asyntai:\n      widget_id: %s\n      enable_on_serve: false\n" % WIDGET_ID)
+    assert "data-asyntai-id" not in html, "widget is on during serve"
+    assert "<h1" in html, "page did not render"
+
+
+# --- in-process hook calls -----------------------------------------------------
+
+def t_hooks_in_process():
+    plugin = AsyntaiPlugin()
+    errors, warnings = plugin.load_config({"widget_id": WIDGET_ID, "enable_on_serve": False})
+    assert not errors, errors
+    plugin.on_startup(command="build", dirty=False)
+    plugin.on_config({})
+    page = "<html><body>a</body></html>"
+    assert WIDGET_ID in plugin.on_post_page(page, page=None, config={})
+    assert plugin.on_post_template("x", template_name="sitemap.xml", config={}) == "x"
+    assert WIDGET_ID in plugin.on_post_template(page, template_name="search.html", config={})
+    plugin.on_startup(command="serve", dirty=False)
+    assert plugin.on_post_page(page, page=None, config={}) == page
+
+
+def t_entry_point():
+    from importlib.metadata import entry_points
+
+    eps = entry_points()
+    group = eps.select(group="mkdocs.plugins") if hasattr(eps, "select") else eps.get("mkdocs.plugins", [])
+    match = [ep for ep in group if ep.name == "asyntai"]
+    assert match, "entry point asyntai is not registered"
+    assert match[0].load() is not None
+
+
+if __name__ == "__main__":
+    print("mkdocs-ai-chatbot tests")
+    for name, fn in [
+        ("insert before the LAST </body>", t_insert_last_body),
+        ("insert works with upper case </BODY >", t_insert_uppercase),
+        ("insert appends when there is no body", t_insert_no_body),
+        ("build: mkdocs theme, every page + 404 has one tag", t_theme_mkdocs),
+        ("build: readthedocs theme", t_theme_readthedocs),
+        ("build: Material for MkDocs", t_theme_material),
+        ("build: Material with navigation.instant", t_theme_material_instant),
+        ("missing widget_id stops the build", t_missing_id),
+        ("blank widget_id stops the build", t_empty_id),
+        ("malformed widget_id stops the build", t_bad_id),
+        ("widget_id of wrong type stops the build", t_wrong_type),
+        ("widget_id with spaces is trimmed", t_trimmed_id),
+        ("custom script_url is used", t_custom_script_url),
+        ("existing snippet in a theme override is kept, no second tag", t_existing_snippet_kept),
+        ("</body> inside a code block is left alone", t_body_in_code_block),
+        ("site without the plugin has no tag", t_no_plugin_no_tag),
+        ("mkdocs serve: widget is on by default", t_serve_default_on),
+        ("mkdocs serve: enable_on_serve false keeps it off", t_serve_off),
+        ("hooks in process: build vs serve, sitemap untouched", t_hooks_in_process),
+        ("entry point 'asyntai' resolves", t_entry_point),
+    ]:
+        check(name, fn)
+    print("\n%d passed, %d failed" % (len(passed), len(failed)))
+    sys.exit(1 if failed else 0)