Sgwrsbot AI gyda ffynonellau i MkDocs

Mae themâu MkDocs yn datgelu cyfeiriaduron override gwahanol, a gall Material lywio rhwng tudalennau heb ail-lwytho'n llwyr. Rhaid i integreiddiad gwydn gadw sgriptiau presennol y thema, llwytho'r teclyn unwaith, a chydweithio â chwilio a llywio symudol.

Awdur ac adolygydd technegol: Michael Fisher, cynhaliwr ChattyBox. Cyhoeddwyd ac archwiliwyd yn dechnegol 10 Gorffennaf 2026. Mae'r protocol dilysu isod yn diwtorial gweithredu; ni honnir unrhyw ganlyniad o ran traffig, dargyfeirio na chywirdeb atebion.

1. Dewis y cyfeiriadur override cywir

Ar gyfer Material for MkDocs, cyfeiriwch custom_dir at gyfeiriadur overrides:

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

Ar gyfer y thema adeiledig, defnyddiwch gyfeiriadur thema pwrpasol ar wahân:

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

Mae cadw'r amrywiadau ar wahân yn egluro pa dempled sylfaen gwreiddiol sy'n cael ei ymestyn.

2. Ymestyn y bloc scripts

Crëwch overrides/main.html ar gyfer Material neu custom_theme/main.html ar gyfer y thema adeiledig:

{% 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 %}

Mae {{ super() }} yn cadw'r sgriptiau a ddarperir gan y thema, gan gynnwys ymddygiad llywio a chwilio. Gall ei hepgor wneud i'r teclyn ymddangos fel pe bai'n gweithio, tra'n torri rhyngwyneb y ddogfennaeth yn dawel. Mae'r ID sefydlog hefyd yn rhoi gwiriad uniongyrchol ar gyfer llwythwr dyblyg.

Defnyddiwch werthoedd penodol i'r project o'r cyfeirnod gosod teclyn. Mae'r canllaw chatbot AI MkDocs yn ymdrin â chwmpas ffynonellau, ymddygiad cropian a'r cwestiynau i'w gwerthuso cyn cyhoeddi.

3. Adeiladu'r ddau amrywiad

O'ch project MkDocs, rhedwch:

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

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

Mae --strict yn troi rhybuddion yn fethiannau, gan ddal problemau llywio a ffurfweddu sydd wedi torri cyn i'r teclyn gael ei werthuso.

4. Rhedeg y gwiriadau porwr

Gweinyddwch bob amrywiad a gwiriwch:

1. Mae chwilio adeiledig yn dal i agor ac yn dychwelyd y canlyniad dogfennaeth disgwyliedig.
2. Mae llywio ar unwaith Material yn newid llwybrau heb ddyblygu llwythwr y teclyn.
3. Mae document.querySelectorAll('#chattybox-widget').length yn aros yn 1 ar ôl sawl newid llwybr.
4. Ar olwg o 390 px, nid yw'r lansiwr yn gorchuddio chwilio, llywio na rheolyddion nesaf/blaenorol.
5. Mae cwestiwn a gefnogir yn dyfynnu'r dudalen ddisgwyliedig, ac mae cwestiwn nas cefnogir yn cynhyrchu ymateb wrth gefn gofalus.

Mae'r pedwar gwiriad cyntaf yn dilysu ymddygiad integreiddio. Mae'r pumed yn dibynnu ar y tudalennau rydych yn eu mynegeio ac yn gofyn am set werthuso gynrychioliadol; dilynwch y canllaw cropian a'r rhestr wirio lansio yn hytrach na thrin llwyth sgript llwyddiannus fel prawf o ansawdd atebion.

5. Cadw CSP cyfyngol

Caniatewch westeiwr y teclyn yn script-src, tarddiad yr API wedi'i ffurfweddu yn connect-src, a tharddiadau'r ffontiau yn style-src ac font-src pan fo angen. Mae'r teclyn cyfredol yn mewnosod arddulliau cydrannau, felly mae angen strategaeth arddulliau inline benodol ar bolisi sydd fel arall yn llym. Osgowch restrau ffynhonnell â chardiau gwyllt.

Rhestr wirio cynnal a chadw

Ailadeiladwch y ddau amrywiad thema ar ôl uwchraddio MkDocs neu Material, oherwydd gall enwau blociau templedi gwreiddiol newid. Cadwch ID y sgript yn sefydlog, cadwch super(), ac ail-redwch y gwiriadau chwilio, llywio ar unwaith, gorgyffwrdd symudol a dyfynnu ffynonellau.

Ar gyfer cynllunio cyflwyno o'r dechrau i'r diwedd, defnyddiwch y rhestr wirio gweithredu chatbot dogfennaeth.

Ffynonellau

• Cyfeirnod gosod teclyn ChattyBox
• Addasu themâu MkDocs
• Addasu Material for MkDocs
• Canllaw Content Security Policy MDN