Neidio i'r prif gynnwys
ChattyBoxDechrau am ddim

Sgwrsbot AI gyda ffynonellau i MkDocs

· 4 munud o ddarllen
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 yn helpu i gyfrif y sgript hon; nid yw'n canfod llwythwr arall sydd ag ID gwahanol neu heb ID.

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​

Lawrlwythwch a dadbaciwch yr enghreifftiau MkDocs, yna rhedwch y gorchmynion hyn o'r cyfeiriadur examples/mkdocs-chattybox sydd wedi'i ddadbacio. Mae'n cynnwys requirements.txt a'r projectau material a vanilla ar wahân. Ar gyfer project presennol, defnyddiwch ei ddibyniaethau a'i gyfeiriadur ei hun yn lle hynny.

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; profwch a yw cwestiynau nas cefnogir yn cael ymateb wrth gefn gofalus heb gymryd yn ganiataol y bydd y cynorthwyydd yn ymatal rhag ateb bob tro.

Dim ond y sgript hon y mae'r cyfrif ID yn ei gynnwys; archwiliwch integreiddiadau eraill a'r teclyn wedi'i rendro am ddyblygiadau hefyd. 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 tharddiad unrhyw ddelwedd eicon pwrpasol yn img-src. Ar gyfer fersiwn 16 y teclyn yn y cod ffynhonnell cyfredol, caniatewch darddiadau Google Fonts yn style-src ac font-src pan fewnosodir ei daflen arddull Inter; gwiriwch ymddygiad y llwythwr sydd wedi'i ddefnyddio. 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​