Siirry pääsisältöön
ChattyBoxAloita ilmaiseksi

AI-chatbot lähdeviitteillä Docusaurus 3:een

· 3 minuutin luku
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 suojaa juuri tämän lisäyksen Reactin kehitysaikaisten uudelleenliitosten ja asiakaspuolen reittimuutosten yhteydessä. Se ei tunnista erillistä lataajaa, jolla on toinen tunniste tai ei tunnistetta lainkaan; käytä sivulla vain yhtä integraatiota.

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ä.
  • Nykyisen lähdekoodin lataajalle https://fonts.googleapis.com style-src-direktiivissä ja https://fonts.gstatic.com font-src-direktiivissä, kun se lisää Inter-tyylitiedoston. Vastaava Google Fonts -tyylitiedoston linkki estää lisäämisen; pelkkä fontin muu saatavuus ei estä sitä. Tarkista käyttöönotetun lataajan toiminta.
  • Mahdollisen määritetyn mukautetun kuvakekuvan alkuperä img-src-direktiivissä.
  • 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ä kysymyksiä, joihin ei ole tukea, ja arvioi, käyttääkö avustaja varavastausta lähteen keksimisen sijaan; toista testi edustavilla tapauksilla olettamatta, että se pidättäytyy vastaamasta joka kerta.
  5. Testaa widgetin käynnistintä kapeassa mobiilinäkymässä ja tarkista, ettei se peitä navigointi- tai sivutusohjaimia.

Skriptimäärän tarkistus laskee vain kyseisen tunnisteen; erillinen lataaja ilman tunnistetta tai toisella tunnisteella voi silti olla olemassa. Tarkista myös kaikki integraatiot ja renderöity widget. Määrä 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​