Jamdesk Documentation logo

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:

docs.json
{
  "styling": {
    "js": "/script.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.

A detecção automática inclui todos os arquivos .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:

docs.json
{
  "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)

script.js
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

script.js
// 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

script.js
// 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ê

O que vem a seguir?

CSS personalizado

Substitua estilos do tema com CSS personalizado

Exemplos de CSS e JS

Um botão flutuante Ask AI e um cabeçalho com a marca

Integrações

Análises nativas e integrações de terceiros