mkdocs-biel 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ """Ask AI chatbot plugin for MkDocs, powered by Biel.ai.
2
+
3
+ (c) 2024 - present Biel.ai
4
+ This code is licensed under MIT license (see LICENSE for details).
5
+ """
6
+
7
+ __version__ = "0.1.0"
mkdocs_biel/plugin.py ADDED
@@ -0,0 +1,185 @@
1
+ """
2
+ Ask AI chatbot plugin for MkDocs.
3
+
4
+ (c) 2024 - present Biel.ai
5
+ This code is licensed under MIT license (see LICENSE for details).
6
+ """
7
+
8
+ import logging
9
+ from html import escape
10
+
11
+ from mkdocs.config import config_options
12
+ from mkdocs.plugins import BasePlugin
13
+
14
+ log = logging.getLogger("mkdocs.plugins.biel")
15
+
16
+ DEFAULT_OPTIONS = {
17
+ "enable": True,
18
+ "version": "latest",
19
+ "theme_shortcuts_fix": True,
20
+ # biel-button
21
+ "project": None,
22
+ "button_position": "bottom-right",
23
+ "button_text": "Ask AI",
24
+ "button_style": "dark",
25
+ "custom_font": None,
26
+ "hide_icon": None,
27
+ "ai_icon": None,
28
+ "hide_avatars": None,
29
+ "api_key": None,
30
+ "metadata": None,
31
+ # biel-bot
32
+ "disable_input": None,
33
+ "email": None,
34
+ "expand_modal": None,
35
+ "hide_close_button": None,
36
+ "hide_connect_button": None,
37
+ "hide_expand_button": None,
38
+ "hide_refresh_button": None,
39
+ "hide_settings_button": None,
40
+ "hide_sources": None,
41
+ "hide_feedback": None,
42
+ "hide_think_mode_button": None,
43
+ "hide_tooltips": None,
44
+ "initial_messages": None,
45
+ "keep_conversation": None,
46
+ "modal_position": "bottom-right",
47
+ "show_terms_modal": None,
48
+ "think_mode_enabled": None,
49
+ # biel-bot text
50
+ "assistant_label": None,
51
+ "close_button_text": None,
52
+ "collapse_button_text": None,
53
+ "connect_button_text": None,
54
+ "error_message_4_0_3": None,
55
+ "error_message_4_0_4": None,
56
+ "error_message_default": None,
57
+ "expand_button_text": None,
58
+ "footer_text": None,
59
+ "header_title": "Biel.ai chatbot",
60
+ "input_placeholder_text": None,
61
+ "mcp_claude_copied_description": None,
62
+ "mcp_claude_description": None,
63
+ "mcp_claude_text": None,
64
+ "mcp_copied_text": None,
65
+ "mcp_copilot_description": None,
66
+ "mcp_copilot_text": None,
67
+ "mcp_cursor_description": None,
68
+ "mcp_cursor_text": None,
69
+ "mcp_server_url": None,
70
+ "mcp_url_copied_description": None,
71
+ "mcp_url_description": None,
72
+ "mcp_url_text": None,
73
+ "refresh_button_text": None,
74
+ "send_button_text": None,
75
+ "settings_button_text": None,
76
+ "sources_text": None,
77
+ "suggested_questions": None,
78
+ "suggested_questions_title": None,
79
+ "terms_checkbox_text": None,
80
+ "terms_description": None,
81
+ "terms_title": None,
82
+ "think_mode_auto_description": None,
83
+ "think_mode_auto_text": None,
84
+ "think_mode_button_text": None,
85
+ "think_mode_fast_description": None,
86
+ "think_mode_fast_text": None,
87
+ "think_mode_think_description": None,
88
+ "think_mode_think_text": None,
89
+ "welcome_message": None,
90
+ }
91
+
92
+ # Options that configure the plugin itself rather than the <biel-button> element.
93
+ NON_ATTRIBUTE_OPTIONS = ("enable", "version", "button_text", "theme_shortcuts_fix")
94
+
95
+ # Themes like Material for MkDocs register global keyboard shortcuts (f, s, /,
96
+ # p, n) that fire while the user types inside Biel's shadow DOM, because the
97
+ # retargeted event doesn't look editable to the theme. Stop propagation at the
98
+ # document only for keystrokes originating inside a Biel component, so theme
99
+ # shortcuts keep working everywhere else.
100
+ THEME_SHORTCUTS_FIX = """\
101
+ <script>
102
+ document.addEventListener('keydown', function (e) {
103
+ var path = e.composedPath ? e.composedPath() : [];
104
+ for (var i = 0; i < path.length; i++) {
105
+ var tag = path[i].tagName;
106
+ if (tag && tag.toLowerCase().indexOf('biel-') === 0) {
107
+ e.stopPropagation();
108
+ return;
109
+ }
110
+ }
111
+ });
112
+ </script>
113
+ """
114
+
115
+
116
+ def _snake_to_kebab(string):
117
+ return string.replace("_", "-")
118
+
119
+
120
+ def _build_config_scheme():
121
+ scheme = []
122
+ for key, default in DEFAULT_OPTIONS.items():
123
+ if isinstance(default, bool):
124
+ scheme.append((key, config_options.Type(bool, default=default)))
125
+ elif default is not None:
126
+ scheme.append((key, config_options.Type(str, default=default)))
127
+ else:
128
+ scheme.append(
129
+ (key, config_options.Optional(config_options.Type((str, bool, int))))
130
+ )
131
+ return tuple(scheme)
132
+
133
+
134
+ class BielPlugin(BasePlugin):
135
+ config_scheme = _build_config_scheme()
136
+
137
+ def on_config(self, config):
138
+ if self.config.get("enable") and not self.config.get("project"):
139
+ log.warning(
140
+ "biel: no 'project' set. Add your project ID from the "
141
+ "Biel.ai dashboard to mkdocs.yml."
142
+ )
143
+ return config
144
+
145
+ def on_post_page(self, output, page, config):
146
+ if not self.config.get("enable"):
147
+ return output
148
+
149
+ version = self.config.get("version") or "latest"
150
+ head_tags = (
151
+ f'<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/'
152
+ f'biel-search@{version}/dist/biel-search/biel-search.css">\n'
153
+ f'<script type="module" src="https://cdn.jsdelivr.net/npm/'
154
+ f'biel-search@{version}/dist/biel-search/biel-search.esm.js"></script>\n'
155
+ )
156
+
157
+ attributes = []
158
+ for key in DEFAULT_OPTIONS:
159
+ if key in NON_ATTRIBUTE_OPTIONS:
160
+ continue
161
+ value = self.config.get(key)
162
+ if value is None:
163
+ continue
164
+ if isinstance(value, bool):
165
+ value = "true" if value else "false"
166
+ attributes.append(
167
+ f'{_snake_to_kebab(key)}="{escape(str(value), quote=True)}"'
168
+ )
169
+
170
+ button_text = escape(str(self.config.get("button_text") or "Ask AI"))
171
+ button = f'<biel-button {" ".join(attributes)}>{button_text}</biel-button>\n'
172
+ if self.config.get("theme_shortcuts_fix"):
173
+ button += THEME_SHORTCUTS_FIX
174
+
175
+ if "</head>" in output:
176
+ output = output.replace("</head>", head_tags + "</head>", 1)
177
+ else:
178
+ output = head_tags + output
179
+
180
+ if "</body>" in output:
181
+ output = output.replace("</body>", button + "</body>", 1)
182
+ else:
183
+ output += button
184
+
185
+ return output
@@ -0,0 +1,89 @@
1
+ Metadata-Version: 2.4
2
+ Name: mkdocs-biel
3
+ Version: 0.1.0
4
+ Summary: Ask AI chatbot plugin for MkDocs, powered by Biel.ai.
5
+ Keywords: mkdocs,mkdocs-plugin,ai,chatbot,search,documentation,ask-ai,rag
6
+ Author-email: TechDocs Studio <info@techdocs.studio>
7
+ Requires-Python: >=3.8
8
+ Description-Content-Type: text/markdown
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ License-File: LICENSE
14
+ Requires-Dist: mkdocs>=1.4
15
+ Project-URL: Documentation, https://docs.biel.ai/installation/mkdocs
16
+ Project-URL: Home, https://github.com/TechDocsStudio/mkdocs-biel
17
+
18
+ # AI chatbot plugin for MkDocs
19
+
20
+ Ask AI chatbot plugin for MkDocs sites, powered by [Biel.ai](https://biel.ai).
21
+
22
+ ![AI chatbot MkDocs](https://docs.biel.ai/assets/images/biel-widget-docs-bd28548cf26a37bcb7c496487280bbfe.png)
23
+
24
+ Add an AI chatbot to your MkDocs documentation using Biel.ai's plugin. The integration works with any MkDocs theme, including Material for MkDocs, and adds both chat and search capabilities. No template overrides needed.
25
+
26
+ *Note: A Biel.ai plan is required to use this plugin. Try it free for 14 days—no credit card required.*
27
+
28
+ ## Key features
29
+
30
+ - AI chatbot that provides instant responses to documentation queries.
31
+ - AI search engine for quick and relevant information retrieval.
32
+ - Integration with MkDocs, no `custom_dir` or template overrides required.
33
+ - Customizable to match your site's branding and user needs.
34
+
35
+ ## Installation
36
+
37
+ ```bash
38
+ pip install mkdocs-biel
39
+ ```
40
+
41
+ Add the plugin to your `mkdocs.yml`:
42
+
43
+ ```yaml
44
+ plugins:
45
+ - search
46
+ - biel:
47
+ project: <YOUR_PROJECT_ID>
48
+ header_title: Biel.ai chatbot
49
+ ```
50
+
51
+ Replace `<YOUR_PROJECT_ID>` with your project's ID from the [Biel.ai dashboard](https://app.biel.ai).
52
+
53
+ Run `mkdocs serve` and verify the chat button appears in the bottom-right corner.
54
+
55
+ ## Configuration
56
+
57
+ All widget options are supported as snake_case keys, for example:
58
+
59
+ ```yaml
60
+ plugins:
61
+ - biel:
62
+ project: <YOUR_PROJECT_ID>
63
+ button_text: Ask AI
64
+ button_position: bottom-right
65
+ modal_position: bottom-right
66
+ button_style: dark
67
+ header_title: Documentation AI
68
+ ```
69
+
70
+ Set `enable: false` to turn the widget off without removing the configuration.
71
+
72
+ ### Theme keyboard shortcuts
73
+
74
+ Some themes, including Material for MkDocs, register global keyboard shortcuts (`f`, `s`, `/`, `p`, `n`) that fire while typing inside the Biel.ai widget. The plugin fixes this automatically: keystrokes inside the widget are scoped to it, and theme shortcuts keep working everywhere else on the page. Set `theme_shortcuts_fix: false` to opt out.
75
+
76
+ ## Get started
77
+
78
+ See the [MkDocs AI chatbot integration guide](https://docs.biel.ai/installation/mkdocs) for the full list of options and setup instructions.
79
+
80
+ ## Support
81
+
82
+ Need assistance? [Contact us](https://docs.biel.ai/support) for help.
83
+
84
+ ## License
85
+
86
+ Copyright (c) 2024 Biel.ai
87
+
88
+ Licensed under the [MIT License](LICENSE).
89
+
@@ -0,0 +1,7 @@
1
+ mkdocs_biel/__init__.py,sha256=RvF5SRtdeyXSIKD7YptMIfBUt3YnC9u7Y2l8G4DIGOo,179
2
+ mkdocs_biel/plugin.py,sha256=aovY37UnAu0ziCA8J0LqCeCBMWzz3v9PayNerxbxeHI,5885
3
+ mkdocs_biel-0.1.0.dist-info/entry_points.txt,sha256=nZL_HF2c8ot-P5edJKuLSdY8vwTun-r1Ad2x-XztGf0,53
4
+ mkdocs_biel-0.1.0.dist-info/licenses/LICENSE,sha256=Iswh4l-k6fOZeKmtFbDd_bJjuVOgNJcKJZ7uAVZrUv8,1051
5
+ mkdocs_biel-0.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
6
+ mkdocs_biel-0.1.0.dist-info/METADATA,sha256=z1wUM_biDO9n-Sl2RF2x4XPv80_xS-Oa5YSgD1Mfx8E,3002
7
+ mkdocs_biel-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: flit 3.12.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [mkdocs.plugins]
2
+ biel=mkdocs_biel.plugin:BielPlugin
3
+
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2023 Biel.ai
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.