Chatbot de IA com citações para Docusaurus 3

Depois do primeiro carregamento, o Docusaurus comporta-se como uma aplicação de página única. Uma integração de widget que funciona apenas no documento inicial, ou que adiciona um segundo loader a cada mudança de rota, não está pronta para produção. Este guia usa uma identidade de script estável e uma raiz de tema que permanece montada em todas as rotas da documentação.

Autor e revisor técnico: Michael Fisher, responsável pela manutenção do ChattyBox. Publicado e verificado tecnicamente em 10 de julho de 2026. As verificações reproduzíveis abaixo são um tutorial de implementação, não um benchmark de desempenho ou precisão.

1. Adicione o componente de tema Root

Crie src/theme/Root.tsx no seu site 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}</>;
}

O ID estável chattybox-widget é a parte importante. O React Strict Mode pode remontar efeitos durante o desenvolvimento, e o Docusaurus muda de rota sem substituir o documento. A proteção torna ambos os casos idempotentes.

Use o URL da API mostrado pelo seu projeto ChattyBox em vez de copiar um deployment de exemplo. Consulte a referência de instalação do widget para ver os atributos atuais e o guia de produto do Docusaurus para orientações sobre seleção de fontes e avaliação.

2. Mantenha o loader montado

Não coloque este script dentro de uma página individual da documentação ou de um layout que o Docusaurus substitui durante a navegação. O componente Root personalizado por swizzling envolve a aplicação durante toda a sua vida útil, por isso o widget continua disponível enquanto os visitantes passam entre guias e referências.

Se o seu site já tiver src/theme/Root.tsx, integre o efeito ao componente existente em vez de substituir provedores de autenticação, analytics ou outros.

3. Considere a Content Security Policy

Uma política restritiva precisa permitir:

• https://chattybox.ai em script-src para o loader do widget.
• A origem da API de chat configurada em connect-src.
• https://fonts.googleapis.com em style-src e https://fonts.gstatic.com em font-src se a fonte do widget ainda não estiver disponível.
• Estilos inline de componentes em style-src para a versão atual do widget.

Comece pela política existente e adicione apenas as origens que realmente usa. Não substitua uma política restritiva por um wildcard amplo.

4. Reproduza as verificações de integração

No seu projeto Docusaurus, adicione o wrapper Root acima e execute:

bun install
bun run start

Em seguida, verifique:

1. Abra duas rotas diferentes da documentação sem atualizar completamente o navegador.
2. Execute document.querySelectorAll('#chattybox-widget').length depois de cada navegação. O resultado deve permanecer 1.
3. Faça uma pergunta respondida por uma página indexada e confirme que a resposta contém um link para essa página.
4. Faça uma pergunta sem suporte e confirme que o assistente recorre ao fallback em vez de inventar uma fonte.
5. Teste o launcher numa viewport móvel estreita e confirme que ele não cobre os controles de navegação ou paginação.

A verificação da contagem de scripts comprova a prevenção de duplicados. Ela não comprova a qualidade da recuperação. Use um conjunto representativo de perguntas e o guia de scraping para validar a cobertura das fontes antes do lançamento.

O que monitorizar depois do lançamento

Registe perguntas não resolvidas, citações incorretas, páginas de fonte desatualizadas e rotas em que o launcher obscurece os controles do site. Faça novos testes depois de atualizações do tema Docusaurus, pois alterações na navegação e no layout do conteúdo podem afetar o posicionamento mesmo quando o loader continua correto.

Para uma sequência de implementação mais ampla, use o checklist de implementação de chatbot para documentação e o checklist de lançamento.

Fontes

• Referência de instalação do widget ChattyBox
• Documentação de swizzling do Docusaurus
• Guia de Content Security Policy da MDN