Adicione um chatbot de IA com citações ao MkDocs
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 também fornece uma asserção direta contra loaders duplicados.
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
No seu projeto MkDocs:
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:
- A pesquisa integrada continua a abrir e a devolver o resultado de documentação esperado.
- A navegação instantânea do Material muda de rota sem duplicar o loader do widget.
document.querySelectorAll('#chattybox-widget').lengthcontinua a ser1depois de várias mudanças de rota.- Numa viewport de 390 px, o launcher não cobre a pesquisa, a navegação nem os controles seguinte/anterior.
- Uma pergunta suportada cita a página esperada, e uma pergunta sem suporte produz um fallback conservador.
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 as origens das fontes em style-src e font-src quando necessário. 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.