Ga naar de hoofdinhoud
ChattyBoxStart gratis

AI-chatbot met bronvermelding in MkDocs

· 4 min lezen
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 helpt dit script te tellen; deze detecteert geen andere loader met een andere of ontbrekende ID.

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​

Download en pak de MkDocs-voorbeelden uit en voer deze opdrachten uit vanuit de uitgepakte map examples/mkdocs-chattybox. Die bevat requirements.txt en de afzonderlijke projecten material en vanilla. Gebruik voor een bestaand project in plaats daarvan de eigen afhankelijkheden en projectmap.

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:

  1. De ingebouwde zoekfunctie opent nog steeds en geeft het verwachte documentatieresultaat terug.
  2. Material instant navigation wijzigt routes zonder de widget-loader te dupliceren.
  3. document.querySelectorAll('#chattybox-widget').length blijft 1 na meerdere routewijzigingen.
  4. Bij een viewport van 390 px bedekt de launcher zoeken, navigatie en de knoppen voor vorige/volgende niet.
  5. Een ondersteunde vraag verwijst naar de verwachte pagina; test bij niet-ondersteunde vragen of de fallback terughoudend is, zonder aan te nemen dat de assistent altijd afziet van een antwoord.

De ID-telling omvat alleen dat script; controleer ook andere integraties en de weergegeven widget op duplicaten. 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 origin van een eventuele aangepaste pictogramafbeelding in img-src. Sta voor widget v16 uit de huidige broncode de Google Fonts-origins toe in style-src en font-src wanneer het Inter-stylesheet wordt geïnjecteerd; controleer het gedrag van de uitgerolde loader. 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.

Bronnen​