Přejít na hlavní obsah
ChattyBoxZačít zdarma

AI chatbot s citacemi pro Docusaurus 3

· 4 min čtení
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

Docusaurus se po prvním načtení stránky chová jako jednostránková aplikace. Integrace widgetu, která funguje pouze v počátečním dokumentu nebo při každé změně trasy připojuje další loader, není připravena pro produkční použití. Tato příručka používá stabilní identitu skriptu a kořen tématu, který zůstává připojený napříč trasami dokumentace.

Autor a technický recenzent: Michael Fisher, správce ChattyBoxu. Publikováno a technicky ověřeno 10. července 2026. Níže uvedené opakovatelné kontroly jsou návodem k implementaci, nikoli benchmarkem výkonu nebo přesnosti.

1. Přidejte kořenovou komponentu tématu​

Ve svém webu Docusaurus vytvořte 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}</>;
}

Stabilní ID chattybox-widget chrání toto konkrétní vložení při opětovném připojení Reactu během vývoje a změnách tras na straně klienta. Neodhalí však samostatný loader s jiným nebo chybějícím ID; na stránce používejte pouze jednu integraci.

Použijte URL API zobrazené ve vašem projektu ChattyBox namísto kopírování ukázkového nasazení. Aktuální atributy najdete v referenci instalace widgetu; doporučení k výběru zdrojů a vyhodnocování obsahuje produktová příručka Docusaurus.

2. Udržujte loader připojený​

Tento skript nevkládejte do jednotlivé stránky dokumentace ani do layoutu, který Docusaurus při navigaci nahrazuje. Swizzlovaná komponenta Root obaluje aplikaci po celou dobu jejího životního cyklu, takže widget zůstává dostupný, když návštěvníci přecházejí mezi průvodci a referenčními stránkami.

Pokud váš web už src/theme/Root.tsx obsahuje, začleňte efekt do existující komponenty namísto nahrazení autentizace, analytiky nebo jiných providerů.

3. Zohledněte Content Security Policy​

Restriktivní zásada musí povolit:

  • https://chattybox.ai v script-src pro loader widgetu.
  • Nakonfigurovaný origin chatovacího API v connect-src.
  • Pro loader z aktuálního zdrojového kódu https://fonts.googleapis.com v style-src a https://fonts.gstatic.com v font-src, když vkládá stylopis fontu Inter. Odpovídající odkaz na stylopis Google Fonts tomuto vložení zabrání; samotná dostupnost fontu nestačí. Ověřte chování nasazeného loaderu.
  • Origin obrázku jakékoli nakonfigurované vlastní ikony v img-src.
  • Inline styly komponent v style-src pro aktuální build widgetu.

Vycházejte ze stávající zásady a přidejte pouze originy, které skutečně používáte. Nenahrazujte restriktivní zásadu širokým zástupným znakem.

4. Zopakujte integrační kontroly​

Do svého projektu Docusaurus přidejte výše uvedený wrapper Root a spusťte:

bun install
bun run start

Poté ověřte:

  1. Otevřete dvě různé trasy dokumentace bez úplného obnovení prohlížeče.
  2. Po každé navigaci spusťte document.querySelectorAll('#chattybox-widget').length. Hodnota musí zůstat 1.
  3. Položte otázku, na kterou odpovídá indexovaná stránka, a ověřte, že odpověď odkazuje na tuto stránku.
  4. Položte nepodporované otázky a vyhodnoťte, zda asistent použije fallback namísto vymyšlení zdroje; opakujte test s reprezentativními případy a nepředpokládejte, že se vždy zdrží odpovědi.
  5. Otestujte spouštěč v úzkém mobilním viewportu a zkontrolujte, že nezakrývá navigaci ani ovládací prvky stránkování.

Kontrola počítá pouze toto ID; samostatný loader bez ID nebo s jiným ID může stále existovat. Zkontrolujte také všechny integrace a vykreslený widget. Počet nedokazuje kvalitu vyhledávání. Před spuštěním použijte reprezentativní sadu otázek a průvodce scrapingem k ověření pokrytí zdrojů.

Co sledovat po nasazení​

Zaznamenávejte nevyřešené otázky, nesprávné citace, zastaralé zdrojové stránky a trasy, na kterých spouštěč zakrývá ovládací prvky webu. Po aktualizacích tématu Docusaurus testujte znovu, protože změny navigace a rozvržení obsahu mohou ovlivnit umístění, i když loader zůstane správný.

Pro širší postup nasazení použijte kontrolní seznam implementace chatbota pro dokumentaci a kontrolní seznam spuštění.

Zdroje​