Fungerar med Material for MkDocs-sidor
Indexera guider, referenssidor och genererad statisk HTML från offentliga MkDocs- eller Material for MkDocs-distributioner utan att byta ut ditt tema.
En AI-chattbot för dokumentation i MkDocs och Material for MkDocs. ChattyBox genomsöker din offentliga webbplats och kan länka svar till hämtade sidor. Kontrollera att svar och källhänvisningar är korrekta. Ingen Python-indexeringspipeline eller egen RAG att underhålla.
ChattyBox genomsöker din befintliga webbplats, dokumentation, ditt hjälpcenter, CMS eller din kunskapsbas. Hämtat innehåll kan vägleda chatbotens svar; kontrollera att svaren och källhänvisningarna är korrekta.
Genomsök den distribuerade MkDocs-webbplatskartan eller de stabila och versionsbaserade sökvägarna som du avsiktligt stödjer.
Testa frågor om produkten, Python och API:et och öppna varje källhänvisning före installationen.
För Material, konfigurera theme.custom_dir och utöka base.html från overrides/main.html samtidigt som skriptblocket bevaras med super().
Verifiera inbyggd sökning, omedelbar navigering, mobilkontroller, CSP och varje publicerad mike-version.
Lansering i tre steg
MkDocs-team vill vanligtvis ha snabba statiska konstruktioner, tydlig navigering och läsbart tekniskt innehåll. ChattyBox behåller det arbetsflödet intakt samtidigt som en källciterad assistent läggs till ovanpå den publicerade webbplatsen.
Använd dessa kontrollpunkter för att avgöra om ChattyBox ska användas vid sidan av din dokumentationsplattform, ersätta en separat assistent eller användas separat för testning.
Indexera guider, referenssidor och genererad statisk HTML från offentliga MkDocs- eller Material for MkDocs-distributioner utan att byta ut ditt tema.
Peka ChattyBox på versionsvägarna du vill att användarna ska fråga om och testa sedan om svaren citerar de avsedda stabila, senaste eller äldre dokumenten.
Eftersom ChattyBox genomsöker den offentliga webbplatsen behöver team inte lägga till vektorindexering i sin MkDocs-byggpipeline eller sina CI-skript.
På Pro eller Business kan du granska flaggade frågor som heuristiska signaler om möjliga saknade exempel, oklara installationssteg eller föråldrade felsökningssidor.
Material for MkDocs och det inbyggda MkDocs-temat stöder båda mallarv, men de bör använda separata anpassade kataloger. Material-lösningen nedan bevarar skriptblocket med super(), lägger till en asynkron laddare och fungerar vid direktnavigering utan att ersätta sökfunktionen.
Kontrollera mallblocken och omedelbar navigering efter temauppgraderingar och genomsök igen när ett mike-alias flyttas.
| MkDocs-aspekt | Beslut om genomförande | Kontroll |
|---|---|---|
MkDocs-aspekt Åsidosättning i Material | Beslut om genomförande Ställ in theme.name på material och theme.custom_dir på overrides. Utöka base.html, åsidosätt scripts-blocket, anropa super() och lägg sedan till widgetskriptet. | Kontroll Bygg och betjäna webbplatsen och bekräfta sedan att Material-sökning och navigering fortfarande fungerar. |
MkDocs-aspekt Vanilj MkDocs | Beslut om genomförande Använd theme.name: mkdocs med en separat custom_theme-katalog. Lägg till motsvarande överskrivning i custom_theme/main.html i stället för att kopiera Material-mallar. | Kontroll Kör mkdocs serve och verifiera sökningen, nästa och föregående länkar och widgeten på mer än en sida. |
MkDocs-aspekt Asynkron laddning och dubbletter | Beslut om genomförande Behåll en laddare i det ärvda skriptblocket, ge det ett stabilt ID och lägg inte till samma kodavsnitt genom extra_javascript eller en annan del. | Kontroll Bekräfta efter fullständiga sidladdningar och Materials direktövergångar att document.querySelectorAll("#chattybox-widget").length är 1. |
MkDocs-aspekt Innehållssäkerhetspolicy | Beslut om genomförande Tillåt chattybox.ai i script-src, det konfigurerade API-ursprunget i connect-src, fonts.googleapis.com i style-src och fonts.gstatic.com i font-src. Den aktuella widgeten injicerar sin komponent-CSS, så en strikt style-src behöver även 'unsafe-inline' tills en nonce-medveten eller extern stilmallsbyggnad är tillgänglig. | Kontroll Kontrollera webbläsarkonsolen och nätverkspanelen efter blockerade skript-, stil-, typsnitts-, hämtnings- eller WebSocket-förfrågningar. |
MkDocs-aspekt Sök, direktnavigering och mobil | Beslut om genomförande Bevara temats skript med super() och håll startknappen fri från sökdialogen, sidopanelen, sidnumreringen och samtyckeskontrollerna. | Kontroll Testa tangentbordssökning, flera direktlänkar och ett visningsområde på 390 pixlar utan överlappning eller horisontell rullning. |
MkDocs-aspekt mike versioner | Beslut om genomförande Välj medvetet sökvägar för stabila, senaste eller specifika versioner. Genomsök på nytt när ett alias har flyttats och uteslut versioner som inte stöds när svar från andra versioner skulle vilseleda användarna. | Kontroll Använd mike serve för att testa versionsbyte och bekräfta att hänvisningar löser sig i den avsedda versionen. |
MkDocs-aspekt Widget- eller citeringsfel | Beslut om genomförande Kontrollera YAML-indrag, den aktiva custom_dir, ärvt blocknamn, API-nyckel, CSP, innehåll i webbplatskartan och om den distribuerade versionen innehåller åsidosättningen. | Kontroll Inspektera genererad HTML och testa produktionsartefakten istället för att bara förlita sig på live-omladdning. |
Använd en temafråga med en verifierbar mallregel, öppna sedan citatet och bekräfta att det matchar den version som din besökare valde.
Praktisk checklista för att utvärdera AI-chattbotar för dokumentationFör Material for MkDocs, ställ in theme.custom_dir på overrides, utöka base.html i overrides/main.html och anropa super() före det asynkrona widgetskriptet. Vanilla MkDocs behöver en egen anpassad temakatalog och en motsvarande main.html-överstyrning.
{% 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="https://adorable-woodpecker-629.convex.site/chat"
data-chattybox-widget="true"
></script>
{% endblock %}Ja. ChattyBox kan crawla offentliga MkDocs- och Material for MkDocs-sidor och bäddas in som en standardwidget för webbplatser.
Nej. Lägg till widgetens kodavsnitt i webbplatsens mall eller temaöverskrivning efter att du har konfigurerat chattboten.
Ja, om de versionshanterade dokumentationssidorna är offentliga och ingår i genomsökningen eller webbplatskartan.
På Pro eller Business är flaggade frågor heuristiska signaler att undersöka för möjliga luckor, inte definitiva diagnoser av ditt MkDocs-innehåll.