Siirry pääsisältöön
ChattyBoxAloita ilmaiseksi

Lisää lähteisiin viittaava AI-chatbot MkDocsiin

· 3 minuutin luku
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

MkDocs-teemat käyttävät erilaisia ohitushakemistoja, ja Material voi siirtyä sivujen välillä ilman täydellistä uudelleenlatausta. Kestävän integraation on säilytettävä teeman nykyiset skriptit, ladattava widget kerran ja toimittava yhdessä haun ja mobiilinavigoinnin kanssa.

Tekninen kirjoittaja ja tarkastaja: Michael Fisher, ChattyBoxin ylläpitäjä. Julkaistu ja teknisesti tarkistettu 10. heinäkuuta 2026. Alla oleva varmennusmenettely on toteutusopas; sen perusteella ei väitetä mitään liikenteestä, ohjausasteesta tai vastausten tarkkuudesta.

1. Valitse oikea override-hakemisto​

Määritä Material for MkDocsia varten custom_dir osoittamaan overrides-hakemistoon:

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

Käytä sisäänrakennettua teemaa varten erillistä mukautettua teemahakemistoa:

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

Kun versiot pidetään erillään, on selvää, mitä ylemmän tason pohjamallia laajennetaan.

2. Laajenna scripts-lohkoa​

Luo Materialia varten overrides/main.html tai sisäänrakennettua teemaa varten 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äilyttää teeman tarjoamat skriptit, mukaan lukien navigoinnin ja haun toiminnallisuuden. Sen pois jättäminen voi saada widgetin näyttämään toimivalta, vaikka se rikkoisi dokumentaation käyttöliittymän huomaamatta. Vakaa tunniste auttaa laskemaan tämän skriptin; se ei tunnista toista lataajaa, jolla on toinen tunniste tai ei tunnistetta lainkaan.

Käytä projektikohtaisia arvoja widgetin asennusviitteestä. MkDocs AI chatbot -oppaassa käsitellään lähteiden laajuutta, indeksointia ja ennen julkaisua arvioitavia kysymyksiä.

3. Rakenna molemmat versiot​

Lataa ja pura MkDocs-esimerkit ja suorita sitten nämä komennot puretussa examples/mkdocs-chattybox-hakemistossa. Se sisältää requirements.txt-tiedoston ja erilliset material- ja vanilla-projektit. Käytä olemassa olevassa projektissa sen omia riippuvuuksia ja projektihakemistoa.

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

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict muuttaa varoitukset virheiksi. Näin rikkinäinen navigointi ja määritysongelmat havaitaan ennen widgetin arviointia.

4. Suorita selaintarkistukset​

Palvele kumpaakin versiota ja varmista seuraavat:

  1. Sisäänrakennettu haku avautuu edelleen ja palauttaa odotetun dokumentaatiotuloksen.
  2. Materialin pikanavigointi vaihtaa reittiä monistamatta widgetin lataajaa.
  3. document.querySelectorAll('#chattybox-widget').length pysyy arvossa 1 useiden reittimuutosten jälkeen.
  4. 390 pikselin näkymässä widgetin käynnistin ei peitä hakua, navigointia eikä edellinen/seuraava-ohjaimia.
  5. Tuettu kysymys viittaa odotettuun sivuun; testaa, tuottavatko kysymykset, joihin ei ole tukea, varovaisen varavastauksen olettamatta, että avustaja pidättäytyy vastaamasta joka kerta.

Tunnisteen laskenta kattaa vain tämän skriptin; tarkista päällekkäisyydet myös muista integraatioista ja renderöidystä widgetistä. Ensimmäiset neljä tarkistusta validoivat integraation toiminnan. Viides riippuu indeksoitavista sivuista ja edellyttää edustavaa arviointijoukkoa; noudata scraping-opasta ja julkaisun tarkistuslistaa sen sijaan, että pitäisit onnistunutta skriptin latausta osoituksena vastausten laadusta.

5. Säilytä rajoittava CSP​

Salli widgetin isäntä script-src-direktiivissä, määritetty API-alkuperä connect-src-direktiivissä ja mahdollisen mukautetun kuvakekuvan alkuperä img-src-direktiivissä. Salli nykyisen lähdekoodin widget v16:lle Google Fontsin alkuperät style-src- ja font-src-direktiiveissä, kun sen Inter-tyylitiedosto lisätään; tarkista käyttöönotetun lataajan toiminta. Nykyinen widget lisää komponenttityylejä, joten myös muuten tiukka käytäntö tarvitsee erikseen määritetyn inline-tyylistrategian. Vältä lähdeluetteloissa jokerimerkkejä.

Ylläpitotarkistuslista​

Rakenna molemmat teemaversiot uudelleen MkDocs- tai Material-päivitysten jälkeen, sillä ylemmän tason mallien lohkojen nimet voivat muuttua. Pidä skriptin tunniste vakaana, säilytä super() ja suorita haku-, pikanavigointi-, mobiilipäällekkäisyys- ja lähdeviittaustarkistukset uudelleen.

Käytä dokumentaation chatbotin toteutuksen tarkistuslistaa päästä päähän ulottuvaan käyttöönoton suunnitteluun.

Lähteet​