JavaScript personalizado
Adicione JavaScript personalizado ao seu site de documentação para widgets de chat, análises, integrações de terceiros e outras funcionalidades do lado do cliente.
JavaScript personalizado é executado em todas as páginas do seu site de documentação. Use-o para widgets de chat, análises ou qualquer outro script do lado do cliente de que você precisar.
Adicionar JavaScript personalizado
Crie um arquivo JavaScript no diretório da sua documentação e referencie-o em docs.json:
{
"styling": {
"js": "/script.js"
}
}// Your custom JavaScript runs on every page
console.log('Hello from custom JS!');O Jamdesk insere seu script no HTML da página. Ele é executado enquanto a página carrega.
Detecção automática
Sem styling.js, o Jamdesk detecta arquivos .js no diretório raiz do projeto. Coloque um arquivo script.js ao lado do seu docs.json para incluí-lo.
my-docs/
├── docs.json
├── script.js ← auto-detected
├── introduction.mdx
└── getting-started.mdx
Configurar styling.js em docs.json desativa a detecção automática. Apenas os arquivos listados são usados.
.js na raiz do projeto, incluindo scripts utilitários como eslint.config.js ou postcss.config.js. Liste exatamente quais arquivos incluir com styling.js em docs.json.Vários arquivos
Inclua vários scripts passando um array:
{
"styling": {
"js": ["/chat.js", "/analytics.js"]
}
}A detecção automática inclui todos os arquivos .js da raiz, em ordem alfabética. analytics.js é carregado antes de chat.js.
Exemplos
Exemplos de CSS e JS combina um script com CSS. Ele adiciona um botão flutuante Ask AI e um cabeçalho com a cor da marca.
Widget de chat (Crisp)
window.$crisp = [];
window.CRISP_WEBSITE_ID = "your-website-id";
(function () {
var d = document;
var s = d.createElement("script");
s.src = "https://client.crisp.chat/l.js";
s.async = 1;
d.getElementsByTagName("head")[0].appendChild(s);
})();Análises personalizadas
// Track outbound link clicks
document.addEventListener('click', function (e) {
var link = e.target.closest('a[href^="http"]');
if (link && !link.href.includes(window.location.hostname)) {
console.log('Outbound click:', link.href);
// Send to your analytics service
}
});Widget de feedback
// Load a feedback widget after the page is ready
window.addEventListener('load', function () {
var s = document.createElement('script');
s.src = 'https://your-feedback-tool.com/widget.js';
s.setAttribute('data-project', 'your-project-id');
document.body.appendChild(s);
});Como funciona
O build lê seus arquivos JavaScript e os incorpora ao HTML de cada página. A tag script fica no final do <body>. O DOM já está disponível quando seu código é executado.
O JavaScript personalizado também é executado em jamdesk dev (CLI 1.1.222 e posteriores). Teste um script ali antes de publicar. Erros lançados pelo seu script aparecem no console do navegador. window.__JAMDESK_DEV__ é true em jamdesk dev. Use-o para ignorar código exclusivo de produção, como análises:
if (!window.__JAMDESK_DEV__) {
// analytics, chat widgets and other production-only code
}
Se você configurar o consentimento de cookies com integrations.cookies, seu script só é executado no site publicado, depois que o visitante der consentimento.
O script é executado uma vez, quando um visitante carrega o site pela primeira vez. Clicar em um link dentro da documentação troca o conteúdo da página sem recarregá-la por completo. O script não é executado novamente. Código que lê ou altera o conteúdo da página deve observar mudanças de página.
Limitações
- Os scripts são executados em todas as páginas. Não há como direcioná-los a páginas específicas
- As alterações entram em vigor no próximo build
- Os scripts são incorporados ao HTML, não servidos como arquivos separados
- Prefira as integrações nativas para análises. Elas cuidam do consentimento e do desempenho para você
