AI chatbot s citacemi pro Docusaurus 3

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

Nejdůležitější je stabilní ID chattybox-widget. React Strict Mode může během vývoje znovu připojit efekty a Docusaurus mění trasy bez nahrazení dokumentu. Tato kontrola zajišťuje idempotenci v obou případech.

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.
• https://fonts.googleapis.com v style-src a https://fonts.gstatic.com v font-src, pokud font widgetu ještě není dostupný.
• 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 nepodporovanou otázku a ověřte, že asistent použije fallback namísto vymyšlení zdroje.
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čtu skriptů dokazuje prevenci duplicit. Nedokazuje však 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

• Reference instalace widgetu ChattyBox
• Dokumentace swizzlingu Docusaurus
• Průvodce Content Security Policy na MDN