Ga naar de hoofdinhoud
MkDocs-supportbot

Voeg een AI-chatbot met bronvermeldingen toe aan je MkDocs- en Material-documentatie

Een AI-chatbot voor MkDocs- en Material for MkDocs-documentatie. ChattyBox crawlt je openbare site en kan antwoorden linken aan opgehaalde pagina’s. Controleer antwoorden en bronvermeldingen op juistheid. Geen Python-indexeringspijplijn of aangepaste RAG om te onderhouden.

Crawlt gepubliceerde documentatiepagina'sAntwoorden met bronvermeldingenIngesloten met één scriptGeen documentatiemigratie vereistGeen creditcard vereistJe content blijft van jou
Vraag ChattyBox
Waar moet ik beginnen als ik een betrouwbaar antwoord van deze site nodig heb?
Voeg eerst uw openbare website-URL toe aan ChattyBox. Het haalt geïndexeerde inhoud op om antwoorden te sturen en kan bronlinks tonen ter controle. Test antwoorden en terugvalantwoorden vóór de lancering.
iBronnen3^
MkDocs gids
chattybox.ai
Analyse
chattybox.ai
Startpagina
chattybox.ai

Illustratief gesprek — geen livechat.

Aangedreven door ChattyBox

Start een chatbot met bronvermeldingen zonder uw website-stack opnieuw op te bouwen

ChattyBox crawlt uw bestaande website, documentatie, helpcentrum, CMS of kennisbank. Opgehaalde inhoud kan de antwoorden van de chatbot sturen; controleer antwoorden en bronvermeldingen op juistheid.

De Material-override behoudt het JavaScript van het thema en voegt één asynchrone widgetloader toe.
Vanilla MkDocs gebruikt een afzonderlijke map voor een aangepast thema in plaats van uit te gaan van Material-paden.
Controles omvatten het naast elkaar werken van zoeken, instant navigation, dubbele loaders en smalle mobiele viewports.
Met versiebewuste crawlselectie kiest u bewust tussen stabiele, nieuwste en oudere mike-routes.
Workflowstap

Crawl de geïmplementeerde MkDocs-sitemap of de stabiele en versiegebonden paden die u bewust ondersteunt.

Workflowstap

Test product-, Python- en API-vragen en open vóór installatie elke bronvermelding.

Workflowstap

Configureer voor Material theme.custom_dir en breid base.html uit vanuit overrides/main.html, waarbij u het scripts-blok met super() behoudt.

Workflowstap

Controleer de ingebouwde zoekfunctie, instant navigation, mobiele bediening, CSP en elke gepubliceerde mike-versie.

Lancering in drie stappen

Plak de URL van MkDocs, test antwoorden met bronvermeldingen en installeer vervolgens de widget.

MkDocs-specifieke workflow

Conversatieondersteuning voor statische Python-documentatiesites

MkDocs-teams willen meestal snelle statische builds, duidelijke navigatie en leesbare technische inhoud. ChattyBox houdt die workflow intact en voegt een assistent met bronvermeldingen toe aan de gepubliceerde site.

Beslissingspad

Gebruik deze controlepunten om te beslissen of ChattyBox naast uw documentplatform moet worden geplaatst, een afzonderlijke assistent moet vervangen of geïsoleerd moet blijven om te testen.

01

Werkt met Material for MkDocs-pagina's

Indexeer gidsen, referentiepagina's en gegenereerde statische HTML van openbare MkDocs- of Material for MkDocs-implementaties zonder uw thema te vervangen.

02

Ga bewust om met documentatie met versies

Verwijs ChattyBox naar de versiepaden waarover gebruikers vragen mogen stellen en test vervolgens of de antwoorden verwijzen naar de bedoelde stabiele, nieuwste of oudere documentatie.

03

Geen Python-indexeringstaak om te onderhouden

Omdat ChattyBox de openbare site crawlt, hoeven teams geen vectorindexering toe te voegen aan hun MkDocs-buildpijplijn of CI-scripts.

04

Verbeter documenten op basis van echte vragen

Bekijk op Pro of Business gemarkeerde vragen als heuristische signalen van mogelijk ontbrekende voorbeelden, onduidelijke installatiestappen of verouderde probleemoplossingspagina’s.

Getoetst redactioneel bewijs

Geteste installatiepaden voor Material en vanilla MkDocs

Material for MkDocs en het ingebouwde MkDocs-thema ondersteunen beide template-overerving, maar moeten afzonderlijke aangepaste mappen gebruiken. Het onderstaande Material-pad behoudt het scripts-blok met super(), voegt één asynchrone loader toe en blijft werken bij instant navigation zonder het zoekgedrag te vervangen.

Technisch auteur
ChattyBox-documentatieteam
Technisch reviewer
ChattyBox-engineeringteam
Laatst bijgewerkt
Informatie gecontroleerd
MkDocs, Material for MkDocs en mike

Controleer templateblokken en het gedrag van instant navigation opnieuw na thema-upgrades en crawl opnieuw wanneer een mike-alias wordt verplaatst.

Material for MkDocs-configuratie van custom_dir en override van het hoofdtemplate met behoud van themascripts
Oorspronkelijke installatiereferentie: theme.custom_dir selecteert de override en super() houdt de zoek- en navigatiescripts van Material intact.
Installatiebeslissingen voor Material en vanilla MkDocs met end-to-endcontroles.
MkDocs-aandachtspuntImplementatiebeslissingVerificatie
MkDocs-aandachtspunt
Material-override
Implementatiebeslissing
Stel theme.name in op material en theme.custom_dir op overrides. Breid base.html uit, override scripts, roep super() aan en voeg daarna het widgetscript toe.
Verificatie
Build en serve de site en bevestig vervolgens dat zoeken en navigeren in Material nog werken.
MkDocs-aandachtspunt
Vanilla MkDocs
Implementatiebeslissing
Gebruik theme.name: mkdocs met een afzonderlijke map custom_theme. Voeg de overeenkomstige override custom_theme/main.html toe in plaats van Material-templates te kopiëren.
Verificatie
Voer mkdocs serve uit en controleer de zoekfunctie, links naar de volgende en vorige pagina en de widget op meer dan één pagina.
MkDocs-aandachtspunt
Asynchroon laden en duplicaten
Implementatiebeslissing
Behoud één loader in het overgeërfde scripts-blok, geef deze een stabiele ID en voeg hetzelfde fragment niet toe via extra_javascript of een andere partial.
Verificatie
Bevestig na volledige laadacties en directe Material-overgangen dat document.querySelectorAll("#chattybox-widget").length 1 is.
MkDocs-aandachtspunt
Content Security Policy
Implementatiebeslissing
Sta chattybox.ai toe in script-src, de geconfigureerde API-origin in connect-src, fonts.googleapis.com in style-src en fonts.gstatic.com in font-src. De huidige widget injecteert zijn eigen component-CSS, dus een strenge style-src heeft ook 'unsafe-inline' nodig totdat een nonce-bewuste of externe stylesheet-build beschikbaar is.
Verificatie
Controleer de browserconsole en het paneel Network op geblokkeerde script-, style-, font-, fetch- of WebSocket-verzoeken.
MkDocs-aandachtspunt
Zoeken, instant navigation en mobiel
Implementatiebeslissing
Behoud themascripts met super() en houd de launcher vrij van het zoekvenster, de drawer, paginering en toestemmingsbediening.
Verificatie
Test zoeken met het toetsenbord, meerdere directe links en een viewport van 390 pixels zonder overlapping of horizontaal scrollen.
MkDocs-aandachtspunt
mike-versies
Implementatiebeslissing
Kies bewust stabiele, nieuwste of expliciete versiepaden. Crawl opnieuw nadat een alias is verplaatst en sluit niet-ondersteunde releases uit wanneer antwoorden over versies heen gebruikers zouden misleiden.
Verificatie
Gebruik mike serve om wisselen tussen versies te testen en bevestig dat bronvermeldingen binnen de bedoelde versie werken.
MkDocs-aandachtspunt
Fout met widget of bronvermelding
Implementatiebeslissing
Controleer YAML-inspringing, de actieve custom_dir, de naam van het overgeërfde blok, de API-sleutel, CSP, de inhoud van de sitemap en of de geïmplementeerde build de override bevat.
Verificatie
Inspecteer de gegenereerde HTML en test het productieartefact in plaats van alleen op live reload te vertrouwen.
Controle van antwoord met bronvermelding

Test een antwoord tegen de actieve versie

Gebruik een themavraag met een verifieerbare templateregel, open vervolgens de bronvermelding en bevestig dat deze overeenkomt met de versie die uw bezoeker heeft geselecteerd.

Praktische evaluatiechecklist voor AI-documentatiechatbots
Stel een vraag aan de MkDocs-gidsen
Hoe voeg ik de widget toe zonder de zoekfunctie van Material te verstoren?
Stel theme.custom_dir in op overrides, maak overrides/main.html, breid base.html uit en voeg de asynchrone loader na super() toe in het scripts-blok. Door super() aan te roepen blijven de scripts behouden die Material gebruikt voor zoeken en navigeren.

Illustratief gesprek — geen livechat.

Aangedreven door ChattyBox
Mobiele Material for MkDocs-pagina waarop zoeken en ChattyBox zichtbaar zijn zonder overlappende bedieningselementen
Oorspronkelijke mobiele referentie: zoeken blijft beschikbaar, de launcher heeft een bruikbaar aanraakdoel en de pagina scrolt niet horizontaal.
Installatiepad

Hoe de widget aan MkDocs toe te voegen

Stel voor Material for MkDocs theme.custom_dir in op overrides, breid base.html uit in overrides/main.html en roep super() aan vóór het asynchrone widgetscript. Vanilla MkDocs heeft een eigen aangepaste themamap en een overeenkomstige main.html-override nodig.

  1. 1Maak een ChattyBox-project en voer uw MkDocs- of Material for MkDocs-site-URL of sitemap in.
  2. 2Test echte MkDocs-vragen in het dashboard en controleer of de bronvermeldingen naar de juiste pagina's verwijzen.
  3. 3Voeg de geteste override toe, bouw de site en verifieer zoek-, navigatie-, CSP- en mobiel gedrag.
overrides/main.html
html
{% 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 %}
Veelgestelde vragen

Veelgestelde vragen

1

Werkt ChattyBox met Material for MkDocs?

Ja. ChattyBox kan openbare MkDocs- en Material for MkDocs-pagina’s crawlen en als standaard websitewidget worden ingebed.

2

Moet ik mijn Python-buildpipeline wijzigen?

Nee. Voeg de widgetsnippet toe aan je sitesjabloon of thema-override nadat je de chatbot hebt geconfigureerd.

3

Kan de bot antwoorden op basis van versiegebonden documentatie?

Ja, als de versiegebonden documentatiepagina’s openbaar zijn en opgenomen zijn in de crawl of sitemap.

4

Kan het documentatiegaten identificeren?

Op Pro of Business zijn gemarkeerde vragen heuristische signalen om te onderzoeken op mogelijke hiaten, geen definitieve diagnoses van je MkDocs-inhoud.