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.
mkdocs_biel/__init__.py
ADDED
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
|
+

|
|
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,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.
|