AI-chatbot met bronvermelding in MkDocs
MkDocs-thema's bieden verschillende override-mappen, en Material kan tussen pagina's navigeren zonder een volledige herlading. Een duurzame integratie moet de bestaande scripts van het thema behouden, de widget één keer laden en naast zoeken en navigatie op mobiele apparaten werken.
Auteur en technisch reviewer: Michael Fisher, maintainer van ChattyBox. Gepubliceerd en technisch gecontroleerd op 10 juli 2026. Het onderstaande verificatieprotocol is een implementatiehandleiding; er wordt geen resultaat voor verkeer, deflectie of antwoordnauwkeurigheid geclaimd.
1. Kies de juiste override-map
Wijs custom_dir voor Material for MkDocs naar een map overrides:
site_name: My documentation
theme:
name: material
custom_dir: overrides
features:
- navigation.instant
Gebruik voor het ingebouwde thema een afzonderlijke map voor een aangepast thema:
site_name: My documentation
theme:
name: mkdocs
custom_dir: custom_theme
Door de varianten gescheiden te houden, blijft duidelijk welke upstream-basistemplate wordt uitgebreid.
2. Breid het blok scripts uit
Maak overrides/main.html voor Material of custom_theme/main.html voor het ingebouwde thema:
{% extends "base.html" %}
{% block scripts %}
{{ super() }}
<script
id="chattybox-widget"
src="https://chattybox.ai/widget.js"
async
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_CHAT_API_URL"
data-chattybox-widget="true"
></script>
{% endblock %}
{{ super() }} behoudt de scripts die door het thema worden geleverd, inclusief navigatie- en zoekgedrag. Als je dit weglaat, kan het lijken alsof de widget werkt terwijl de documentatie-interface stilletjes wordt verbroken. De stabiele ID biedt je ook een directe controle op dubbele loaders.
Gebruik projectspecifieke waarden uit de installatiereferentie voor de widget. De MkDocs-AI-chatbotgids behandelt de bronomvang, het crawlgedrag en de vragen die je vóór publicatie moet evalueren.
3. Bouw beide varianten
Voer dit uit vanuit je MkDocs-project:
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd material
mkdocs build --strict
cd ../vanilla
mkdocs build --strict
--strict zet waarschuwingen om in fouten. Zo worden problemen met navigatie en configuratie gevonden voordat de widget wordt geëvalueerd.
4. Voer de browsercontroles uit
Serveer beide varianten en controleer het volgende:
- De ingebouwde zoekfunctie opent nog steeds en geeft het verwachte documentatieresultaat terug.
- Material instant navigation wijzigt routes zonder de widget-loader te dupliceren.
document.querySelectorAll('#chattybox-widget').lengthblijft1na meerdere routewijzigingen.- Bij een viewport van 390 px bedekt de launcher zoeken, navigatie en de knoppen voor vorige/volgende niet.
- Een ondersteunde vraag verwijst naar de verwachte pagina en een niet-ondersteunde vraag levert een voorzichtige fallback op.
De eerste vier controles valideren het integratiegedrag. De vijfde hangt af van de pagina's die je indexeert en vereist een representatieve evaluatieset; volg de scrapinghandleiding en de lanceringschecklist in plaats van een geslaagde scriptlading als bewijs voor antwoordkwaliteit te beschouwen.
5. Behoud een restrictieve CSP
Sta de widget-host toe in script-src, de geconfigureerde API-origin in connect-src en de font-origins in style-src en font-src wanneer dat nodig is. De huidige widget injecteert componentstijlen, dus voor een verder strikt beleid is ook een expliciete strategie voor inline stijlen nodig. Vermijd wildcards in lijsten met bronnen.
Onderhoudschecklist
Bouw beide themavarianten opnieuw na upgrades van MkDocs of Material, omdat upstream-templatebloknamen kunnen veranderen. Houd de script-ID stabiel, behoud super() en voer de controles voor zoeken, instant navigation, overlap op mobiel en bronvermelding opnieuw uit.
Gebruik voor end-to-end-uitrolplanning de implementatiechecklist voor een documentatiechatbot.