AI-chatbot lähdeviitteillä Docusaurus 3:een

Docusaurus toimii ensimmäisen sivulatauksen jälkeen yksisivuisen sovelluksen tavoin. Widget-integraatio, joka toimii vain ensimmäisessä dokumentissa tai lisää toisen lataajan jokaisella reittimuutoksella, ei ole tuotantovalmis. Tässä oppaassa käytetään vakaata skripti-identiteettiä ja teeman juurikomponenttia, joka pysyy liitettynä dokumentaatioreittien välillä.

Tekninen kirjoittaja ja tarkastaja: Michael Fisher, ChattyBoxin ylläpitäjä. Julkaistu ja teknisesti tarkistettu 10. heinäkuuta 2026. Alla olevat toistettavat tarkistukset ovat toteutusopas, eivät suorituskyky- tai tarkkuusvertailu.

1. Lisää Root-teemakomponentti

Luo Docusaurus-sivustoosi 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}</>;
}

Vakaa chattybox-widget-tunniste on tässä tärkein asia. React Strict Mode voi liittää efektit uudelleen kehityksen aikana, ja Docusaurus vaihtaa reittejä korvaamatta dokumenttia. Tarkistus tekee molemmista tilanteista idempotentteja.

Käytä ChattyBox-projektisi näyttämää API-URL-osoitetta sen sijaan, että kopioisit esimerkkikäyttöönoton. Katso nykyiset attribuutit widgetin asennusviitteestä sekä lähteiden valintaa ja arviointia koskevat ohjeet Docusaurus-tuoteoppaasta.

2. Pidä lataaja liitettynä

Älä sijoita tätä skriptiä yksittäiselle docs-sivulle tai asetteluun, jonka Docusaurus korvaa navigoinnin aikana. Swizzlattu Root-komponentti ympäröi sovellusta koko sen elinkaaren ajan, joten widget pysyy käytettävissä, kun kävijät siirtyvät oppaiden ja viitteiden välillä.

Jos sivustollasi on jo src/theme/Root.tsx, yhdistä efekti nykyiseen komponenttiin sen sijaan, että korvaisit todennuksen, analytiikan tai muut providerit.

3. Huomioi Content Security Policy

Rajoittavan käytännön on sallittava seuraavat:

• https://chattybox.ai script-src-direktiivissä widgetin lataamista varten.
• Määrittämäsi chat-API:n alkuperä connect-src-direktiivissä.
• https://fonts.googleapis.com style-src-direktiivissä ja https://fonts.gstatic.com font-src-direktiivissä, jos widgetin fontti ei ole jo käytettävissä.
• Inline-komponenttityylit style-src-direktiivissä nykyistä widget-koontia varten.

Lähde nykyisestä käytännöstäsi ja lisää vain ne alkuperät, joita todella käytät. Älä korvaa rajoittavaa käytäntöä laajalla jokerimerkillä.

4. Toista integraatiotarkistukset

Lisää yllä oleva Root-kääre Docusaurus-projektiisi ja suorita:

bun install
bun run start

Varmista sitten seuraavat:

1. Avaa kaksi eri docs-reittiä ilman selaimen täyttä päivitystä.
2. Suorita document.querySelectorAll('#chattybox-widget').length jokaisen navigoinnin jälkeen. Arvon on pysyttävä 1:ssä.
3. Esitä kysymys, johon indeksoitu sivu vastaa, ja varmista, että vastaus sisältää linkin kyseiselle sivulle.
4. Esitä kysymys, johon ei ole tukea, ja varmista, että avustaja käyttää varavastausta lähteen keksimisen sijaan.
5. Testaa widgetin käynnistintä kapeassa mobiilinäkymässä ja tarkista, ettei se peitä navigointi- tai sivutusohjaimia.

Skriptimäärän tarkistus osoittaa päällekkäisten latausten eston. Se ei osoita tiedonhaun laatua. Käytä edustavaa kysymysjoukkoa ja scraping-opasta lähteiden kattavuuden validoimiseen ennen julkaisua.

Mitä seurata julkaisun jälkeen

Kirjaa ratkaisematta jääneet kysymykset, virheelliset lähdeviittaukset, vanhentuneet lähdesivut ja reitit, joilla widgetin käynnistin peittää sivuston ohjaimia. Testaa uudelleen Docusaurus-teeman päivitysten jälkeen, sillä navigoinnin ja sisällön asettelun muutokset voivat vaikuttaa sijoitteluun, vaikka lataaja toimisi edelleen oikein.

Laajempaa käyttöönottojärjestystä varten käytä dokumentaation chatbotin toteutuksen tarkistuslistaa ja julkaisun tarkistuslistaa.

Lähteet

• ChattyBox-widgetin asennusviite
• Docusauruksen swizzling-dokumentaatio
• MDN:n Content Security Policy -opas