Pular para o conteúdo principal
Bot de suporte para MkDocs

Adicione um chatbot de IA com citações de fontes à sua documentação do MkDocs e do Material

Um chatbot de IA para documentação MkDocs e Material for MkDocs. O ChattyBox recolhe conteúdo do seu site público e pode incluir nas respostas ligações para as páginas obtidas. Verifique a exatidão das respostas e citações. Sem pipeline de indexação Python ou RAG personalizado para manter.

Recolhe conteúdo de páginas de documentação publicadasRespostas com citações de fontesIncorpora com um scriptNão é necessário migrar a documentaçãoNão é necessário cartão de créditoO seu conteúdo continua a ser seu
Pergunte ao ChattyBox
Por onde devo começar se precisar de uma resposta fiável deste site?
Comece por adicionar o URL público do seu site ao ChattyBox. Este recupera conteúdo indexado para orientar as respostas e pode apresentar ligações às páginas de origem para os visitantes consultarem. Teste as respostas e as respostas alternativas antes do lançamento.
iFontes3^
MkDocs guia
chattybox.ai
Análises
chattybox.ai
Início
chattybox.ai

Conversa ilustrativa — não é um chat em direto.

Disponibilizado pelo ChattyBox

Lance um chatbot com citações de fontes sem reconstruir a infraestrutura do seu site

O ChattyBox recolhe o conteúdo do seu site, documentação, centro de ajuda, CMS ou base de conhecimento existentes. O conteúdo recuperado pode orientar as respostas do chatbot; verifique a precisão das respostas e das citações.

A substituição do Material preserva o JavaScript do tema e adiciona um único carregador assíncrono do widget.
O MkDocs padrão usa um diretório de tema personalizado separado, em vez de pressupor os caminhos do Material.
As verificações abrangem a coexistência da pesquisa, a navegação instantânea, carregadores duplicados e viewports estreitas de dispositivos móveis.
A seleção de rastreamento com reconhecimento de versão mantém intencionais as rotas stable, latest e legadas do mike.
Etapa do fluxo de trabalho

Recolha o conteúdo do sitemap publicado do MkDocs ou dos caminhos estáveis e versionados que decidiu suportar.

Etapa do fluxo de trabalho

Teste perguntas sobre o produto, Python e API e abra todas as citações antes da instalação.

Etapa do fluxo de trabalho

Para o Material, configure theme.custom_dir e estenda base.html a partir de overrides/main.html, preservando o bloco scripts com super().

Etapa do fluxo de trabalho

Verifique a pesquisa integrada, a navegação instantânea, os controlos em dispositivos móveis, a CSP e cada versão publicada com mike.

Lançamento em três etapas

Cole o URL de MkDocs, teste as respostas com citações e instale o widget.

Fluxo de trabalho específico do MkDocs

Suporte conversacional para sites estáticos de documentação Python

As equipas MkDocs procuram geralmente compilações estáticas rápidas, navegação clara e conteúdo técnico legível. O ChattyBox mantém esse fluxo de trabalho intacto e acrescenta ao site publicado um assistente com citações de fontes.

Caminho de decisão

Use estes pontos de verificação para decidir se o ChattyBox deve funcionar ao lado da sua plataforma de documentação, substituir um assistente separado ou permanecer isolado para testes.

01

Funciona com páginas Material for MkDocs

Indexe guias, páginas de referência e HTML estático gerado de sites públicos MkDocs ou Material for MkDocs sem substituir o seu tema.

02

Gira a documentação versionada de forma deliberada

Indique ao ChattyBox os caminhos das versões sobre as quais pretende que os utilizadores façam perguntas e teste se as respostas citam a documentação estável, mais recente ou antiga pretendida.

03

Sem tarefa de indexação Python para manter

Como o ChattyBox recolhe conteúdo do site público, as equipas não precisam de adicionar indexação vetorial ao pipeline de compilação do MkDocs ou aos scripts de CI.

04

Melhore a documentação a partir de perguntas reais

No Pro ou Business, reveja as perguntas assinaladas como sinais heurísticos de possíveis exemplos em falta, passos de instalação pouco claros ou páginas de resolução de problemas desatualizadas.

Evidências editoriais testadas

Caminhos de instalação testados para Material e MkDocs padrão

Tanto o Material for MkDocs quanto o tema integrado do MkDocs oferecem suporte à herança de templates, mas devem usar diretórios personalizados separados. O caminho do Material abaixo preserva o bloco scripts com super(), adiciona um carregador assíncrono e permanece funcional durante a navegação instantânea sem substituir o comportamento da pesquisa.

Autor técnico
Equipa de documentação do ChattyBox
Revisor técnico
Equipa de engenharia do ChattyBox
Última atualização
Informações verificadas
MkDocs, Material for MkDocs e mike

Verifique novamente os blocos de template e o comportamento da navegação instantânea após atualizações do tema e refaça o rastreamento sempre que um alias do mike mudar.

Configuração de custom_dir do Material for MkDocs e substituição do template principal preservando os scripts do tema
Referência original de instalação: theme.custom_dir seleciona a substituição e super() mantém intactos os scripts de pesquisa e navegação do Material.
Decisões de instalação para Material e MkDocs padrão com verificações de ponta a ponta.
Questão do MkDocsDecisão de implementaçãoVerificação
Questão do MkDocs
Substituição do Material
Decisão de implementação
Defina theme.name como material e theme.custom_dir como overrides. Estenda base.html, substitua scripts, chame super() e depois acrescente o script do widget.
Verificação
Gere o build e sirva o site; depois, confirme que a pesquisa e a navegação do Material ainda funcionam.
Questão do MkDocs
MkDocs padrão
Decisão de implementação
Use theme.name: mkdocs com um diretório custom_theme separado. Adicione a substituição equivalente em custom_theme/main.html, em vez de copiar templates do Material.
Verificação
Execute mkdocs serve e verifique a pesquisa, os links de página anterior e seguinte e o widget em mais de uma página.
Questão do MkDocs
Carregamento assíncrono e duplicados
Decisão de implementação
Mantenha um único carregador no bloco scripts herdado, atribua a ele um ID estável e não adicione o mesmo snippet por extra_javascript ou outra parcial.
Verificação
Após carregamentos completos e transições instantâneas do Material, confirme que document.querySelectorAll("#chattybox-widget").length é 1.
Questão do MkDocs
Política de Segurança de Conteúdo
Decisão de implementação
Permita chattybox.ai em script-src, a origem configurada da API em connect-src, fonts.googleapis.com em style-src e fonts.gstatic.com em font-src. O widget atual injeta o CSS de seu componente, então um style-src estrito também precisa de 'unsafe-inline' até que haja um build com nonce ou stylesheet externo.
Verificação
Verifique no console do navegador e no painel Network se há solicitações de script, style, font, fetch ou WebSocket bloqueadas.
Questão do MkDocs
Pesquisa, navegação instantânea e dispositivos móveis
Decisão de implementação
Preserve os scripts do tema com super() e mantenha o inicializador afastado da caixa de diálogo de pesquisa, do menu lateral, da paginação e dos controles de consentimento.
Verificação
Teste a pesquisa pelo teclado, vários links instantâneos e uma viewport de 390 pixels sem sobreposição nem rolagem horizontal.
Questão do MkDocs
Versões do mike
Decisão de implementação
Escolha deliberadamente caminhos stable, latest ou de versões explícitas. Repita a recolha após mover um alias e exclua versões sem suporte quando respostas de outras versões puderem induzir os utilizadores em erro.
Verificação
Use mike serve para testar a troca de versões e confirmar que as citações são abertas na versão pretendida.
Questão do MkDocs
Falha no widget ou na citação
Decisão de implementação
Verifique a indentação do YAML, o custom_dir ativo, o nome do bloco herdado, a chave da API, a CSP, o conteúdo do sitemap e se o build implantado inclui a substituição.
Verificação
Inspecione o HTML gerado e teste o artefato de produção, em vez de depender apenas do live reload.
Verificação de resposta com citação

Teste uma resposta na versão ativa

Use uma pergunta sobre o tema com uma regra de template verificável; depois, abra a citação e confirme que ela corresponde à versão selecionada pelo visitante.

Lista prática de avaliação de chatbots de IA para documentação
Pergunte aos guias do MkDocs
Como adiciono o widget sem prejudicar a pesquisa do Material?
Defina theme.custom_dir como overrides, crie overrides/main.html, estenda base.html e adicione o carregador assíncrono dentro do bloco scripts após super(). Chamar super() preserva os scripts usados pelo Material para pesquisa e navegação.

Conversa ilustrativa — não é um chat em direto.

Disponibilizado pelo ChattyBox
Página móvel do Material for MkDocs com a pesquisa e a ChattyBox visíveis sem sobrepor os controles
Referência móvel original: a pesquisa permanece disponível, o inicializador tem uma área de toque adequada e a página não rola horizontalmente.
Caminho de instalação

Como adicionar o widget ao MkDocs

Para Material for MkDocs, defina theme.custom_dir como overrides, estenda base.html em overrides/main.html e chame super() antes do script assíncrono do widget. O MkDocs normal precisa do seu próprio diretório de tema personalizado e de uma substituição equivalente em main.html.

  1. 1Crie um projeto no ChattyBox e introduza o URL ou sitemap do site MkDocs ou Material for MkDocs.
  2. 2Teste perguntas reais do MkDocs no painel e confirme se as citações apontam para as páginas certas.
  3. 3Adicione a substituição testada, compile o site e verifique pesquisa, navegação, CSP e comportamento em dispositivos móveis.
overrides/main.html
html
{% 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="https://adorable-woodpecker-629.convex.site/chat"
    data-chattybox-widget="true"
  ></script>
{% endblock %}
Perguntas frequentes

Perguntas comuns

1

O ChattyBox funciona com Material for MkDocs?

Sim. O ChattyBox pode recolher conteúdo de páginas públicas MkDocs e Material for MkDocs e ser incorporado como um widget normal de site.

2

Preciso de alterar o meu pipeline de compilação Python?

Não. Adicione o snippet do widget ao modelo do site ou à substituição do tema depois de configurar o chatbot.

3

O bot pode responder com base em documentação versionada?

Sim, se as páginas de documentação versionada forem públicas e estiverem incluídas na recolha ou no sitemap.

4

Consegue identificar lacunas na documentação?

No Pro ou Business, as perguntas assinaladas são sinais heurísticos de possíveis lacunas a investigar, não diagnósticos definitivos do seu conteúdo MkDocs.