Lisa MkDocs-ile allikaviidetega AI-vestlusbot

MkDocsi teemad kasutavad eri override-kaustu ja Material võib liikuda lehtede vahel ilma täieliku uuesti laadimiseta. Vastupidav integratsioon peab säilitama teema olemasolevad skriptid, laadima widgeti ühe korra ning toimima mobiilis koos otsingu ja navigeerimisega.

Autor ja tehniline ülevaataja: Michael Fisher, ChattyBoxi hooldaja. Avaldatud ja tehniliselt kontrollitud 10. juulil 2026. Allolev kontrolliprotokoll on juurutamisõpetus; liikluse, ümbersuunamise ega vastuste täpsuse tulemusi ei väideta.

1. Vali õige override-kaust

Material for MkDocsi puhul suuna custom_dir kausta overrides:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Sisseehitatud teema jaoks kasuta eraldi kohandatud teemakausta:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Variantide eraldi hoidmine teeb selgeks, millist ülesvoolu baastemplate’it laiendatakse.

2. Laienda skriptiplokki

Loo Materiali jaoks overrides/main.html või sisseehitatud teema jaoks custom_theme/main.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="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} säilitab teema pakutavad skriptid, sealhulgas navigeerimise ja otsingu käitumise. Selle väljajätmisel võib widget näida töötavat, kuid dokumentatsiooniliides võib samal ajal märkamatult katki minna. Stabiilne ID annab ka otsese kontrolli duplikaatlaadija vastu.

Kasuta projektipõhiseid väärtusi widgeti paigaldusviitest. MkDocsi AI-vestlusboti juhend käsitleb allika ulatust, roomamise käitumist ja küsimusi, mida enne avaldamist hinnata.

3. Koosta mõlemad variandid

MkDocsi projektis:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict muudab hoiatused vigadeks, tuvastades katkise navigeerimise ja seadistusprobleemid enne widgeti hindamist.

4. Käivita brauserikontrollid

Käivita kumbki variant ja kontrolli järgmist:

1. Sisseehitatud otsing avaneb endiselt ja tagastab oodatud dokumentatsioonitulemuse.
2. Materiali instant navigation muudab marsruuti widgeti laadijat dubleerimata.
3. document.querySelectorAll('#chattybox-widget').length jääb pärast mitut marsruudimuutust väärtusele 1.
4. 390 px laiuses vaates ei kata käivitaja otsingut, navigeerimist ega järgmise/eelmise lehe juhtnuppe.
5. Toetatud küsimus viitab oodatud lehele ja toetamata küsimus annab ettevaatliku allakäigu.

Esimesed neli kontrolli valideerivad integratsiooni käitumist. Viies sõltub indekseeritavatest lehtedest ja nõuab esinduslikku hindamiskogumit; järgi scrapingu juhendit ja avaldamise kontrollnimekirja, mitte ära pea edukat skripti laadimist vastuse kvaliteedi tõendiks.

5. Säilita piirav CSP

Luba widgeti host asukohas script-src, seadistatud API päritolu asukohas connect-src ning fondi päritolud vajaduse korral asukohtades style-src ja font-src. Praegune widget lisab komponentstiile, seega vajab ka muus osas range poliitika inline-stiilide jaoks selget strateegiat. Väldi wildcard-allikaloendeid.

Hoolduse kontrollnimekiri

Koosta mõlemad teemavariandid pärast MkDocsi või Materiali uuendamist uuesti, sest ülesvoolu template’iplokkide nimed võivad muutuda. Hoia skripti ID stabiilsena, säilita super() ja korda otsingu, instant navigation’i, mobiilse kattumise ning allikaviidete kontrolle.

Tervikliku avaldamise kavandamiseks kasuta dokumentatsiooni vestlusboti juurutamise kontrollnimekirja.

Allikad

• ChattyBoxi widgeti paigaldusviide
• MkDocsi teemade kohandamine
• Material for MkDocsi kohandamine
• MDN-i Content Security Policy juhend