Chatbot AI z cytowaniami dla Docusaurus 3

Po pierwszym załadowaniu strony Docusaurus zachowuje się jak aplikacja jednostronicowa. Integracja widgetu, która działa tylko w początkowym dokumencie albo dołącza drugi loader przy każdej zmianie trasy, nie jest gotowa do użycia produkcyjnego. Ten przewodnik wykorzystuje stabilną identyfikację skryptu oraz główny komponent motywu, który pozostaje zamontowany na wszystkich trasach dokumentacji.

Autor i recenzent techniczny: Michael Fisher, opiekun ChattyBox. Opublikowano i sprawdzono technicznie 10 lipca 2026 r. Poniższe powtarzalne testy są samouczkiem implementacyjnym, a nie testem porównawczym wydajności ani dokładności.

1. Dodaj główny komponent motywu Root

Utwórz src/theme/Root.tsx w swojej witrynie 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}</>;
}

Stabilna identyfikacja chattybox-widget jest tu najważniejsza. React Strict Mode może ponownie montować efekty podczas pracy deweloperskiej, a Docusaurus zmienia trasy bez zastępowania dokumentu. Ta kontrola sprawia, że oba przypadki są idempotentne.

Użyj adresu URL API wyświetlanego przez projekt ChattyBox, zamiast kopiować przykładowe wdrożenie. Zobacz dokumentację instalacji widgetu zawierającą aktualne atrybuty oraz przewodnik produktowy Docusaurus dotyczący wyboru źródeł i ewaluacji.

2. Pozostaw loader zamontowany

Nie umieszczaj tego skryptu na pojedynczej stronie dokumentacji ani w układzie, który Docusaurus zastępuje podczas nawigacji. Zmodyfikowany komponent Root opakowuje aplikację przez cały czas jej działania, dzięki czemu widget pozostaje dostępny, gdy odwiedzający przechodzą między przewodnikami a materiałami referencyjnymi.

Jeśli Twoja witryna ma już src/theme/Root.tsx, połącz efekt z istniejącym komponentem zamiast zastępować uwierzytelnianie, analitykę lub innych dostawców.

3. Uwzględnij Content Security Policy

Restrykcyjna polityka musi zezwalać na:

• https://chattybox.ai w script-src dla loadera widgetu.
• Skonfigurowane źródło API czatu w connect-src.
• https://fonts.googleapis.com w style-src oraz https://fonts.gstatic.com w font-src, jeśli czcionka widgetu nie jest już dostępna.
• Wbudowane style komponentów w style-src dla bieżącej wersji widgetu.

Zacznij od istniejącej polityki i dodaj tylko te źródła, których faktycznie używasz. Nie zastępuj restrykcyjnej polityki szeroką regułą wieloznaczną.

4. Odtwórz testy integracji

W projekcie Docusaurus dodaj powyższy wrapper Root i uruchom:

bun install
bun run start

Następnie sprawdź:

1. Otwórz dwie różne trasy dokumentacji bez pełnego odświeżania przeglądarki.
2. Po każdej nawigacji uruchom document.querySelectorAll('#chattybox-widget').length. Wynik musi pozostać równy 1.
3. Zadaj pytanie, na które odpowiada zindeksowana strona, i sprawdź, czy odpowiedź zawiera odnośnik do tej strony.
4. Zadaj pytanie spoza obsługiwanego zakresu i sprawdź, czy asystent zastosuje bezpieczną odpowiedź awaryjną, zamiast wymyślać źródło.
5. Przetestuj launcher w wąskim widoku mobilnym i sprawdź, czy nie zasłania nawigacji ani elementów paginacji.

Test zliczania skryptów potwierdza zapobieganie duplikatom. Nie potwierdza jednak jakości wyszukiwania. Użyj reprezentatywnego zestawu pytań oraz przewodnika po scrapingu, aby przed uruchomieniem zweryfikować pokrycie źródeł.

Co monitorować po uruchomieniu

Rejestruj nierozwiązane pytania, nieprawidłowe cytowania, nieaktualne strony źródłowe oraz trasy, na których launcher zasłania elementy sterujące witryny. Ponownie testuj integrację po aktualizacjach motywu Docusaurus, ponieważ zmiany w nawigacji i układzie treści mogą wpłynąć na położenie widgetu, nawet gdy loader nadal działa poprawnie.

W przypadku szerszego wdrożenia skorzystaj z listy kontrolnej implementacji chatbota dla dokumentacji oraz listy kontrolnej uruchomienia.

Źródła

• Dokumentacja instalacji widgetu ChattyBox
• Dokumentacja swizzlingu Docusaurus
• Przewodnik MDN po Content Security Policy