AI-chattbot med källhänvisningar i MkDocs
MkDocs-teman använder olika kataloger för åsidosättningar, och Material kan navigera mellan sidor utan en fullständig omladdning. En hållbar integration måste bevara temats befintliga skript, ladda widgeten en gång och fungera tillsammans med sökning och navigering på mobila enheter.
Författare och teknisk granskare: Michael Fisher, underhållsansvarig för ChattyBox. Publicerad och tekniskt granskad den 10 juli 2026. Verifieringsprotokollet nedan är en implementeringsguide; inga resultat för trafik, avledning eller svarens noggrannhet görs gällande.
1. Välj rätt katalog för åsidosättningar
För Material for MkDocs anger du en overrides-katalog för custom_dir:
site_name: My documentation
theme:
name: material
custom_dir: overrides
features:
- navigation.instant
För det inbyggda temat använder du en separat katalog för det anpassade temat:
site_name: My documentation
theme:
name: mkdocs
custom_dir: custom_theme
Genom att hålla varianterna åtskilda blir det tydligt vilken uppströmsbasmall som byggs ut.
2. Utöka scripts-blocket
Skapa overrides/main.html för Material eller custom_theme/main.html för det inbyggda temat:
{% 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() }} bevarar skripten som temat tillhandahåller, inklusive navigerings- och sökbeteendet. Om du utelämnar det kan widgeten se ut att fungera samtidigt som dokumentationsgränssnittet i tysthet slutar fungera. Det stabila ID:t ger också en direkt kontroll av dubbla laddare.
Använd projektspecifika värden från referensen för widgetinstallation. Guiden om AI-chattbotar för MkDocs beskriver källomfattning, crawlingbeteende och vilka frågor du bör utvärdera före publicering.
3. Bygg båda varianterna
Från ditt MkDocs-projekt:
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd material
mkdocs build --strict
cd ../vanilla
mkdocs build --strict
--strict gör varningar till fel, vilket fångar trasig navigering och konfigurationsproblem innan widgeten utvärderas.
4. Kör webbläsarkontrollerna
Publicera varje variant och kontrollera:
- Den inbyggda sökningen öppnas fortfarande och returnerar det förväntade dokumentationsresultatet.
- Materials instant navigation byter rutt utan att duplicera widgetens laddare.
document.querySelectorAll('#chattybox-widget').lengthförblir1efter flera ruttändringar.- Vid en viewport på 390 px täcker startknappen inte sökning, navigering eller kontrollerna för nästa/föregående.
- En fråga som stöds hänvisar till rätt sida, och en fråga som inte stöds ger en försiktig reservåtgärd.
De fyra första kontrollerna validerar integrationsbeteendet. Den femte beror på vilka sidor du indexerar och kräver en representativ utvärderingsuppsättning; följ scraping-guiden och lanseringschecklistan i stället för att se en lyckad skriptladdning som ett bevis på svarskvalitet.
5. Bevara en restriktiv CSP
Tillåt widgetens värd i script-src, det konfigurerade API-ursprunget i connect-src och teckensnittens ursprung i style-src och font-src när det behövs. Den aktuella widgeten injicerar komponentstilar, så även en i övrigt strikt policy behöver en uttrycklig strategi för inline-stilar. Undvik wildcard-listor över källor.
Underhållschecklista
Bygg om båda temavarianterna efter uppgraderingar av MkDocs eller Material, eftersom namn på uppströmsmallens block kan ändras. Håll skriptets ID stabilt, bevara super() och kör om kontrollerna av sökning, instant navigation, mobil överlappning och källhänvisningar.
För planering av en lansering från början till slut använder du checklistan för implementering av dokumentationschattbot.