AI-vestlusbot allikaviidetega Docusaurus 3-le

Pärast esimest lehelaadimist käitub Docusaurus nagu ühe lehe rakendus. Widgeti integratsioon, mis töötab ainult algdokumendis või lisab iga marsruudimuutuse korral teise laadija, ei ole tootmiseks valmis. Selles juhendis kasutatakse stabiilset skriptiidentiteeti ja teemajuurt, mis jääb dokumentatsiooni marsruutidel paigaldatuks.

Autor ja tehniline ülevaataja: Michael Fisher, ChattyBoxi hooldaja. Avaldatud ja tehniliselt kontrollitud 10. juulil 2026. Allolevad korratavad kontrollid on juurutamisõpetus, mitte jõudluse või täpsuse võrdluskatse.

1. Lisa teema Root-komponent

Loo oma Docusauruse saidil src/theme/Root.tsx:

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}</>;
}

Stabiilne chattybox-widget ID on kõige olulisem osa. React Strict Mode võib arenduse ajal efektid uuesti ühendada ja Docusaurus vahetab marsruuti dokumenti asendamata. Kaitse muudab mõlemad juhud idempotentseks.

Kasuta ChattyBoxi projektis näidatud API URL-i, mitte ära kopeeri näidisjuurutust. Praeguste atribuutide kohta vaata widgeti paigaldusviidet ning allikate valimise ja hindamise juhiseid Docusauruse tootejuhendist.

2. Hoia laadija paigaldatuna

Ära paiguta seda skripti üksikule dokumentatsioonilehele ega paigutusse, mille Docusaurus navigeerimise ajal asendab. Swizzle’itud Root-komponent ümbritseb rakendust kogu selle eluea jooksul, nii et widget jääb kättesaadavaks, kui külastajad juhendite ja viidete vahel liiguvad.

Kui saidil on src/theme/Root.tsx juba olemas, ühenda efekt olemasoleva komponendiga, mitte ära asenda autentimise, analüütika ega muid pakkujaid.

3. Arvesta Content Security Policyga

Piirav poliitika peab lubama:

• https://chattybox.ai asukohas script-src widgeti laadija jaoks.
• Seadistatud vestluse API päritolu asukohas connect-src.
• https://fonts.googleapis.com asukohas style-src ja https://fonts.gstatic.com asukohas font-src, kui widgeti font pole veel saadaval.
• Praeguse widgeti järgu inline-komponentstiilid asukohas style-src.

Alusta olemasolevast poliitikast ja lisa ainult päritolud, mida tegelikult kasutad. Ära asenda piiravat poliitikat laia wildcard’iga.

4. Korda integratsioonikontrolle

Lisa oma Docusauruse projektis ülaltoodud Root-ümbris ja käivita:

bun install
bun run start

Seejärel kontrolli järgmist:

1. Ava kaks erinevat dokumentatsiooni marsruuti ilma brauserit täielikult värskendamata.
2. Käivita pärast iga navigeerimist document.querySelectorAll('#chattybox-widget').length. Tulemuseks peab jääma 1.
3. Esita küsimus, millele vastab indekseeritud leht, ja kontrolli, et vastus viitab sellele lehele.
4. Esita toetamata küsimus ja kontrolli, et assistent kasutab varuvastust ega mõtle allikat välja.
5. Testi käivitit kitsas mobiilivaates ja kontrolli, et see ei kataks navigeerimis- ega leheküljevahetuse juhtnuppe.

Skriptiarvu kontroll tõendab duplikaatide vältimist. See ei tõenda otsingu kvaliteeti. Kasuta enne avaldamist allikate katvuse valideerimiseks esinduslikku küsimuste kogumit ja scrapingu juhendit.

Mida pärast avaldamist jälgida

Pane kirja lahendamata küsimused, valed allikaviited, aegunud allikalehed ja marsruudid, kus käivitaja varjab saidi juhtnuppe. Testi pärast Docusauruse teema uuendamist uuesti, sest navigeerimise ja sisu paigutuse muudatused võivad asetust mõjutada ka siis, kui laadija töötab endiselt õigesti.

Laiema avaldamisjärjekorra jaoks kasuta dokumentatsiooni vestlusboti juurutamise kontrollnimekirja ja avaldamise kontrollnimekirja.

Allikad

• ChattyBoxi widgeti paigaldusviide
• Docusauruse swizzling’u dokumentatsioon
• MDN-i Content Security Policy juhend