Pular para o conteúdo principal
ChattyBoxComece grátis

Adicione um chatbot de IA com citações ao MkDocs

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

Os temas do MkDocs expõem diretórios de substituição diferentes, e o Material pode navegar entre páginas sem um recarregamento completo. Uma integração duradoura deve preservar os scripts existentes do tema, carregar o widget uma vez e coexistir com a pesquisa e a navegação em dispositivos móveis.

Autor e revisor técnico: Michael Fisher, responsável pela manutenção do ChattyBox. Publicado e verificado tecnicamente em 10 de julho de 2026. O protocolo de verificação abaixo é um tutorial de implementação; não é reivindicado nenhum resultado de tráfego, deflexão ou precisão das respostas.

1. Escolha o diretório de substituição correto​

Para o Material for MkDocs, aponte custom_dir para um diretório overrides:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Para o tema integrado, use um diretório de tema personalizado separado:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Manter as variantes separadas deixa claro qual template base upstream está a ser estendido.

2. Estenda o bloco de scripts​

Crie overrides/main.html para o Material ou custom_theme/main.html para o tema integrado:

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script
    id="chattybox-widget"
    src="https://chattybox.ai/widget.js"
    async
    data-api-key="YOUR_API_KEY"
    data-api-url="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} preserva os scripts fornecidos pelo tema, incluindo o comportamento de navegação e pesquisa. Omitir esse elemento pode fazer o widget parecer funcionar enquanto quebra silenciosamente a interface da documentação. O ID estável ajuda a contar este script; não deteta outro loader com um ID diferente ou sem ID.

Use valores específicos do projeto da referência de instalação do widget. O guia de chatbot de IA para MkDocs aborda o escopo das fontes, o comportamento do rastreamento e as perguntas que deve avaliar antes de publicar.

3. Compile ambas as variantes​

Descarregue e extraia os exemplos de MkDocs e execute estes comandos a partir do diretório extraído examples/mkdocs-chattybox. Este contém requirements.txt e os projetos separados material e vanilla. Para um projeto existente, use antes as respetivas dependências e o diretório do projeto.

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict transforma avisos em falhas, identificando problemas de navegação e configuração antes de o widget ser avaliado.

4. Execute as verificações no navegador​

Sirva cada variante e verifique:

  1. A pesquisa integrada continua a abrir e a devolver o resultado de documentação esperado.
  2. A navegação instantânea do Material muda de rota sem duplicar o loader do widget.
  3. document.querySelectorAll('#chattybox-widget').length continua a ser 1 depois de várias mudanças de rota.
  4. Numa viewport de 390 px, o launcher não cobre a pesquisa, a navegação nem os controlos seguinte/anterior.
  5. Uma pergunta suportada cita a página esperada; teste perguntas sem suporte para avaliar se o fallback é prudente, sem presumir que todas as respostas se abstenham de responder.

A contagem do ID abrange apenas esse script; verifique também se existem duplicados noutras integrações e no widget apresentado. As primeiras quatro verificações validam o comportamento da integração. A quinta depende das páginas que indexa e requer um conjunto de avaliação representativo; siga o guia de scraping e o checklist de lançamento em vez de tratar um carregamento de script bem-sucedido como prova da qualidade das respostas.

5. Preserve uma CSP restritiva​

Permita o host do widget em script-src, a origem da API configurada em connect-src e a origem de qualquer imagem de ícone personalizado em img-src. Para o widget v16 do código-fonte atual, permita as origens do Google Fonts em style-src e font-src quando a folha de estilo Inter for injetada; verifique o comportamento do loader distribuído. O widget atual injeta estilos de componentes, por isso uma política de resto estrita também precisa de uma estratégia explícita para estilos inline. Evite listas de origens com wildcards.

Checklist de manutenção​

Recompile ambas as variantes do tema depois de atualizações do MkDocs ou do Material, pois os nomes dos blocos de template upstream podem mudar. Mantenha o ID do script estável, preserve super() e repita as verificações de pesquisa, navegação instantânea, sobreposição em dispositivos móveis e citações de fontes.

Para planear o lançamento de ponta a ponta, use o checklist de implementação de chatbot para documentação.

Fontes​