JavaScript personnalisé

Jamdesk vous permet d'ajouter du JavaScript personnalisé qui s'exécute sur chaque page de votre site de documentation. Utilisez-le pour des widgets de chat, de l'analytique ou tout autre script côté client dont vous avez besoin.

Ajouter du JavaScript personnalisé

Créez un fichier JavaScript dans le répertoire de votre documentation et référencez-le dans docs.json :

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

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

Votre script est intégré directement dans le HTML de la page, il s'exécute donc pendant le chargement de celle-ci.

Détection automatique

Si vous ne configurez pas styling.js, Jamdesk détecte automatiquement les fichiers .js à la racine de votre projet. Il suffit de déposer un fichier script.js à côté de votre docs.json pour qu'il soit inclus.

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

Lorsque styling.js est configuré dans docs.json, la détection automatique est désactivée et seuls les fichiers indiqués sont utilisés.

Plusieurs fichiers

Pour inclure plusieurs scripts, passez un tableau :

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

Avec la détection automatique, tous les fichiers .js de la racine sont inclus, triés par ordre alphabétique. Si vous avez analytics.js et chat.js, ils se chargent dans cet ordre.

Exemples

Pour un exemple plus détaillé qui associe un script à du CSS, consultez Exemples CSS et JS. Il ajoute un bouton Ask AI flottant et un en-tête aux couleurs de votre marque.

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

Analytique personnalisée

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

Fonctionnement

Vos fichiers JavaScript sont lus pendant le processus de build et intégrés directement dans le HTML de chaque page. La balise script est placée à la fin de <body>, de sorte que le DOM est disponible lorsque votre code s'exécute.

Le JavaScript personnalisé s'exécute aussi dans jamdesk dev (CLI 1.1.222 et versions ultérieures), ce qui vous permet de tester un script avant de faire un push. Les erreurs levées par votre script apparaissent dans la console du navigateur. Dans jamdesk dev, window.__JAMDESK_DEV__ vaut true, vous pouvez donc ignorer le code réservé à la production, comme l'analytique :

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

Si vous configurez le consentement aux cookies avec integrations.cookies, votre script ne s'exécute que sur le site publié, une fois le consentement donné.

Le script s'exécute une seule fois, lorsqu'un visiteur charge votre site pour la première fois. Cliquer sur un lien à l'intérieur de la documentation remplace le contenu de la page sans rechargement complet, le script ne s'exécute donc pas à nouveau. Si votre code manipule le contenu de la page, surveillez les changements de page.

Limites

• Les scripts s'exécutent sur chaque page : il n'est pas possible de cibler des pages précises
• Les modifications sont prises en compte au build suivant
• Les scripts sont intégrés au HTML, et non servis comme des fichiers distincts
• Pour l'analytique, envisagez plutôt d'utiliser les intégrations intégrées, qui gèrent automatiquement le consentement et les performances

Et ensuite ?