Lisää lähteisiin viittaava AI-chatbot MkDocsiin
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 antaa myös suoran kaksoislataajan tarkistuksen.
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
Suorita MkDocs-projektisi juuresta:
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:
- Sisäänrakennettu haku avautuu edelleen ja palauttaa odotetun dokumentaatiotuloksen.
- Materialin pikanavigointi vaihtaa reittiä monistamatta widgetin lataajaa.
document.querySelectorAll('#chattybox-widget').lengthpysyy arvossa1useiden reittimuutosten jälkeen.- 390 pikselin näkymässä widgetin käynnistin ei peitä hakua, navigointia eikä edellinen/seuraava-ohjaimia.
- Tuettu kysymys viittaa odotettuun sivuun ja kysymys, johon ei ole tukea, tuottaa varovaisen varavastauksen.
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ä sekä fonttien alkuperät style-src- ja font-src-direktiiveissä tarvittaessa. 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.