mkdocs-ai-chatbot 1.0.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_ai_chatbot/__init__.py,sha256=v3LZicucHNaZKzOxDTGEkVG-hRolcsT81Wntgw8QMbg,127
+mkdocs_ai_chatbot/plugin.py,sha256=4CkU4huow3xnyNYM6N_adr5zDYIsji5_f68PBrJLDkY,3763
+mkdocs_ai_chatbot-1.0.0.dist-info/licenses/LICENSE,sha256=jGsodKzosaT2Pr7P3ahTkLrMTHQ6uvf111OMRXeGYUM,1064
+mkdocs_ai_chatbot-1.0.0.dist-info/METADATA,sha256=fuvSA6riXy9W2xfCxRrR6Sj9aN74sUYrGxgQ4uKyud0,3255
+mkdocs_ai_chatbot-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mkdocs_ai_chatbot-1.0.0.dist-info/entry_points.txt,sha256=U5gzeZGsakSRvvUO8YnKzjxgpqfgLlYLkbQpmLDNDy0,66
+mkdocs_ai_chatbot-1.0.0.dist-info/top_level.txt,sha256=DjEphkVuJzJrQ4z64GXe7ZyJkicG3fNig4U7uVIRGaQ,18
+mkdocs_ai_chatbot-1.0.0.dist-info/RECORD,,

mkdocs_ai_chatbot-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_ai_chatbot-1.0.0.dist-info/entry_points.txt

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

mkdocs_ai_chatbot-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

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