Sgwrsbot AI gyda dyfyniadau yn Docusaurus 3

Mae Docusaurus yn ymddwyn fel cymhwysiad un dudalen ar ôl llwytho'r dudalen gyntaf. Nid yw integreiddiad teclyn sydd ond yn gweithio ar y ddogfen gychwynnol, neu sy'n atodi llwythwr arall ar bob newid llwybr, yn barod ar gyfer cynhyrchu. Mae'r canllaw hwn yn defnyddio hunaniaeth sgript sefydlog a gwraidd thema sy'n parhau wedi'i osod ar draws llwybrau dogfennaeth.

Awdur ac adolygydd technegol: Michael Fisher, cynhaliwr ChattyBox. Cyhoeddwyd ac archwiliwyd yn dechnegol 10 Gorffennaf 2026. Mae'r gwiriadau ailadroddadwy isod yn diwtorial gweithredu, nid yn feincnod perfformiad na chywirdeb.

1. Ychwanegu cydran Root y thema

Crëwch src/theme/Root.tsx yn eich safle Docusaurus:

import React, { useEffect, type ReactNode } from 'react';

const WIDGET_ID = 'chattybox-widget';

export default function Root({ children }: { children: ReactNode }) {
  useEffect(() => {
    if (document.getElementById(WIDGET_ID)) return;

    const script = document.createElement('script');
    script.id = WIDGET_ID;
    script.src = 'https://chattybox.ai/widget.js';
    script.async = true;
    script.dataset.apiKey = 'YOUR_API_KEY';
    script.dataset.apiUrl = 'YOUR_CHAT_API_URL';
    script.dataset.chattyboxWidget = 'true';
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Yr ID sefydlog chattybox-widget yw'r rhan bwysig. Gall React Strict Mode osod effeithiau eto yn ystod datblygu, a gall Docusaurus newid llwybrau heb ddisodli'r ddogfen. Mae'r gwarchodwr yn gwneud y ddau achos yn idempotent.

Defnyddiwch yr URL API a ddangosir gan eich project ChattyBox yn hytrach na chopïo gosodiad enghreifftiol. Gweler y priodoleddau cyfredol yn y cyfeirnod gosod teclyn a chanllawiau dewis a gwerthuso ffynonellau yn y canllaw cynnyrch Docusaurus.

2. Cadw'r llwythwr wedi'i osod

Peidiwch â rhoi'r sgript hon mewn tudalen ddogfennaeth unigol nac mewn cynllun y mae Docusaurus yn ei ddisodli wrth lywio. Mae'r gydran Root sydd wedi'i swizzlo yn lapio'r cymhwysiad am ei oes, felly mae'r teclyn yn parhau ar gael wrth i ymwelwyr symud rhwng canllawiau a chyfeiriadau.

Os oes gan eich safle src/theme/Root.tsx eisoes, cyfunwch yr effaith â'r gydran bresennol yn hytrach na disodli dilysu, dadansoddeg neu ddarparwyr eraill.

3. Ystyried Content Security Policy

Rhaid i bolisi cyfyngol ganiatáu'r canlynol:

• https://chattybox.ai yn script-src ar gyfer y llwythwr teclyn.
• Tarddiad eich API sgwrs wedi'i ffurfweddu yn connect-src.
• https://fonts.googleapis.com yn style-src a https://fonts.gstatic.com yn font-src os nad yw ffont y teclyn ar gael eisoes.
• Arddulliau cydrannau inline yn style-src ar gyfer adeilad cyfredol y teclyn.

Dechreuwch o'ch polisi presennol ac ychwanegwch yr union darddiadau rydych yn eu defnyddio. Peidiwch â disodli polisi cyfyngol â cherdyn gwyllt eang.

4. Ailadrodd y gwiriadau integreiddio

Ychwanegwch yr amlen Root uchod at eich project Docusaurus a rhedwch:

bun install
bun run start

Yna gwiriwch y canlynol:

1. Agorwch ddau lwybr dogfennaeth gwahanol heb adnewyddu'r porwr yn llawn.
2. Rhedwch document.querySelectorAll('#chattybox-widget').length ar ôl pob llywio. Rhaid iddo aros yn 1.
3. Gofynnwch gwestiwn y mae tudalen wedi'i mynegeio yn ei ateb a chadarnhewch fod yr ymateb yn cysylltu â'r dudalen honno.
4. Gofynnwch gwestiwn nad oes cefnogaeth iddo a chadarnhewch fod y cynorthwyydd yn defnyddio ymateb wrth gefn yn hytrach na dyfeisio ffynhonnell.
5. Profwch y lansiwr mewn golygfan symudol gul a gwiriwch nad yw'n gorchuddio rheolyddion llywio na thudaleniad.

Mae'r gwiriad cyfrif sgript yn profi atal dyblygu. Nid yw'n profi ansawdd adalw. Defnyddiwch set gwestiynau gynrychioliadol a'r canllaw cropian i ddilysu cwmpas ffynonellau cyn lansio.

Beth i'w fonitro ar ôl lansio

Cofnodwch gwestiynau heb eu datrys, ddyfyniadau anghywir, hen dudalennau ffynhonnell a llwybrau lle mae'r lansiwr yn cuddio rheolyddion y safle. Ailbrofwch ar ôl uwchraddio thema Docusaurus, oherwydd gall newidiadau i'r llywio a chynllun y cynnwys effeithio ar leoliad hyd yn oed pan fo'r llwythwr yn parhau'n gywir.

Ar gyfer trefn gyflwyno ehangach, defnyddiwch y rhestr wirio gweithredu chatbot dogfennaeth a'r rhestr wirio lansio.

Ffynonellau

• Cyfeirnod gosod teclyn ChattyBox
• Dogfennaeth swizzling Docusaurus
• Canllaw Content Security Policy MDN