Pular para o conteúdo principal
ChattyBoxComece grátis

Chatbot de IA com citações para Docusaurus 3

· 4 min de leitura
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 protege esta inserção específica contra remontagens do React durante o desenvolvimento e mudanças de rota no lado do cliente. Não deteta um loader separado com um ID diferente ou sem ID; use apenas uma integração por página.

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.
  • Para o loader do código-fonte atual, https://fonts.googleapis.com em style-src e https://fonts.gstatic.com em font-src quando este injeta a folha de estilo Inter. Uma ligação correspondente à folha de estilo do Google Fonts impede essa injeção; a mera disponibilidade da fonte não é suficiente. Verifique o comportamento do loader distribuído.
  • A origem de qualquer imagem de ícone personalizado configurada em img-src.
  • 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 perguntas sem suporte e avalie se o assistente recorre ao fallback em vez de inventar uma fonte; repita com casos representativos sem presumir que todas as respostas se abstenham de responder.
  5. Teste o launcher numa viewport móvel estreita e confirme que ele não cobre os controlos de navegação ou paginação.

A contagem de scripts abrange apenas esse ID; pode continuar a existir um loader separado sem ID ou com um ID diferente. Verifique também todas as integrações e o widget apresentado. A contagem 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 controlos 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​