JavaScript personalizado

Jamdesk te permite añadir JavaScript personalizado que se ejecuta en cada página de tu sitio de documentación. Úsalo para widgets de chat, analítica o cualquier otro script del lado del cliente que necesites.

Añadir JavaScript personalizado

Crea un archivo JavaScript en tu directorio de documentación y referéncialo en docs.json:

{
  "styling": {
    "js": "/script.js"
  }
}

// Your custom JavaScript runs on every page
console.log('Hello from custom JS!');

Tu script se inserta directamente en el HTML de la página, por lo que se ejecuta cuando la página se carga.

Detección automática

Si no configuras styling.js, Jamdesk detecta automáticamente los archivos .js en el directorio raíz de tu proyecto. Solo coloca un archivo script.js junto a tu docs.json y será incluido.

my-docs/
├── docs.json
├── script.js      ← auto-detected
├── introduction.mdx
└── getting-started.mdx

Cuando styling.js está configurado en docs.json, la detección automática se desactiva y solo se usan los archivos especificados.

Múltiples archivos

Incluye múltiples scripts pasando un array:

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

Con la detección automática, todos los archivos .js en el directorio raíz se incluyen, ordenados alfabéticamente. Si tienes analytics.js y chat.js, se cargan en ese orden.

Ejemplos

Para un recorrido más largo que combina un script con CSS, consulta Ejemplos de CSS y JS. Agrega un botón flotante de Ask AI y un encabezado con el color de tu 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);
})();

Analítica personalizada

// 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 comentarios

// 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);
});

Cómo funciona

Tus archivos JavaScript se leen durante el proceso de build y se insertan directamente en el HTML de cada página. La etiqueta script se coloca al final de <body>, por lo que el DOM está disponible cuando se ejecuta tu código.

JavaScript personalizado también se ejecuta en jamdesk dev (CLI 1.1.222 y posteriores), así que puedes probar un script antes de hacer push. Los errores que lance tu script aparecen en la consola del navegador. En jamdesk dev, window.__JAMDESK_DEV__ es true, de modo que puedes omitir código solo de producción, como la analítica:

if (!window.__JAMDESK_DEV__) {
  // analytics, chat widgets and other production-only code
}

Si configuras el consentimiento de cookies con integrations.cookies, tu script se ejecuta solo en el sitio publicado, después de que el visitante dé su consentimiento.

El script se ejecuta una sola vez, cuando un visitante carga tu sitio por primera vez. Al hacer clic en un enlace dentro de la documentación, el contenido de la página se reemplaza sin una recarga completa, por lo que el script no vuelve a ejecutarse. Si tu código trabaja con el contenido de la página, detecta los cambios de página.

Limitaciones

• Los scripts se ejecutan en cada página — no hay forma de apuntarlos a páginas específicas
• Los cambios surten efecto en tu próximo build
• Los scripts se insertan en el HTML, no se sirven como archivos separados
• Para analítica, considera usar las integraciones integradas, que gestionan el consentimiento y el rendimiento automáticamente

¿Qué sigue?