Intégrer une page

Votre changelog existe déjà dans votre documentation. Ce guide place un déclencheur « What's new? » dans votre propre produit : un bouton ou un lanceur flottant qui ouvre ces mêmes entrées dans une fenêtre modale, avec un point qui signale les mises à jour non lues par visiteur. Vous collez une seule balise <script> ; Jamdesk héberge et versionne le widget.

Les captures d'écran montrent l'interface en anglais.

Le changelog est le cas courant, celui autour duquel le point non lu est conçu. Le même widget peut toutefois ouvrir n'importe quelle page de documentation dans la fenêtre modale. Faites pointer data-page là où une page ciblée et contextuelle est utile (voir Faire pointer la fenêtre modale vers n'importe quelle page).

Essayez-le en direct

Cette page exécute le widget réel. Cliquez ci-dessous et la même fenêtre modale que vos visiteurs obtiennent s'ouvre ici même, chargeant le changelog de ce site :

Ce bouton en direct est le composant MDX <Widget>, le moyen le plus simple d'intégrer le widget dans une page de documentation Jamdesk : c'est une balise unique, elle ne nécessite aucun script, et elle résout votre site automatiquement. L'extrait <script> ci-dessous concerne l'autre cas, l'intégration du widget dans votre propre produit ou application, où les composants MDX ne s'exécutent pas. Même widget et même fenêtre modale dans les deux cas ; le reste de cette page couvre le script.

Prérequis

• Un site Jamdesk publié sur son sous-domaine *.jamdesk.app (le widget se charge toujours depuis là, même si vous servez aussi la documentation sur un domaine personnalisé).
• Une page changelog construite à partir d'entrées <Update> avec rss: true dans son frontmatter (voir Activer avec rss: true).

Démarrage rapide

Ouvrez votre dashboard, accédez à Integrations → What's New widget, définissez la page et les options du lanceur, puis copiez l'extrait généré. Voici à quoi il ressemble :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-theme="auto"
  async
></script>

Collez-le dans le HTML de votre application, avant la balise fermante </body>. Au chargement, il ajoute un lanceur flottant What's new dans le coin. En cliquant dessus, votre changelog s'ouvre dans une fenêtre modale ; un point non lu apparaît lorsqu'il y a une entrée que le visiteur n'a pas encore vue.

Épingler une version ou s'auto-héberger

Le widget est open source, et l'extrait hébergé ci-dessus sert toujours la dernière version, ce qui est le bon choix par défaut pour la plupart des sites. Si vous préférez figer une version connue ou servir le fichier vous-même, le dépôt jamdesk-widget propose deux autres façons de le charger.

Épinglez une version avec jsDelivr. Chargez une release taguée depuis le CDN et les octets ne changent jamais sous vos pieds :

<script
  src="https://cdn.jsdelivr.net/gh/jamdesk/jamdesk-widget@v1.0.0/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  async
></script>

Auto-hébergement. Téléchargez widget.js depuis la dernière release et servez-le depuis votre propre origine. Cela aide lorsqu'une politique script-src stricte exclut les scripts tiers.

Dans les deux cas, définissez data-base sur votre origine *.jamdesk.app : l'extrait hébergé la lit depuis l'URL du script lui-même, mais un CDN ou votre propre serveur ne le peut pas. Chaque release publie un hash Subresource Integrity vous permettant d'épingler les octets exacts. Le README du dépôt détaille les trois méthodes d'installation.

Activer avec rss: true

Le widget lit l'entrée la plus récente depuis le même flux qui alimente votre RSS, donc une page n'alimente le widget que lorsque son frontmatter définit rss: true :

---
title: Changelog
rss: true
---

<Update label="June 2026" date="2026-06-01">

**Spec validation at build time.** Every deploy validates the OpenAPI specs your `docs.json` references.

</Update>

Sans rss: true, le widget se charge mais n'affiche aucune entrée et le lanceur reste caché. Une page de documentation qui se contente de démontrer le composant <Update> (sans rss: true) est volontairement exclue, de sorte qu'une date de démonstration n'allume jamais le point.

Configurer l'extrait

Chaque option est un attribut data- sur la balise script. La carte du dashboard les écrit pour vous, mais vous pouvez aussi modifier l'extrait manuellement.

Faire pointer la fenêtre modale vers n'importe quelle page

data-page ouvre n'importe quel chemin de votre site de documentation, pas seulement /changelog. La fenêtre modale affiche la page que vous indiquez, comme une annonce isolée ou une note de migration, dépouillée de l'habillage du site. Pointez-le là où une page ciblée et contextuelle est utile :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/announcements/2026-migration"
  data-unread="off"
  async
></script>

Deux comportements restent liés au flux de votre changelog, à garder en tête lorsque la page n'est pas un changelog :

• Le point non lu suit l'entrée la plus récente de votre changelog, pas la page affichée dans la fenêtre modale. Définissez data-unread="off" lorsque la fenêtre modale ouvre autre chose, sinon le point s'allume pour des mises à jour du changelog que le visiteur n'y voit jamais.
• Le lanceur flottant n'apparaît automatiquement qu'une fois que votre changelog a une entrée (voir Activer avec rss: true). Pour intégrer une page sur un site sans changelog, liez-vous à votre propre élément avec data-trigger. Votre élément s'affiche dans tous les cas.

Modes du lanceur

Lorsque vous vous liez à votre propre élément, le widget ajoute le point non lu à cet élément et ne rend jamais de bouton flottant (data-position et data-label ne s'appliquent alors plus) :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-trigger="#whats-new"
  async
></script>

Définir la taille de la fenêtre modale

La fenêtre modale s'ouvre à 560 × 680 px. Définissez data-width et data-height pour le modifier. Un simple nombre est interprété comme des pixels, ou utilisez n'importe quelle valeur px, vw, vh, rem, em ou % :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-width="720px"
  data-height="600px"
  async
></script>

Les deux dimensions sont plafonnées de façon responsive (92vw de large, 86vh de haut), afin qu'une grande taille tienne quand même sur un téléphone. Une valeur non reconnue revient à la valeur par défaut. Les coins ont par défaut un rayon de 12px ; définissez data-radius (n'importe quelle longueur CSS) pour les rendre plus carrés ou plus arrondis.

Styliser le bouton du lanceur

Le lanceur flottant est une pilule sombre par défaut. Recolorez-le avec data-button-color (arrière-plan) et data-button-text-color (texte), chacun une valeur hexadécimale ou un nom de couleur CSS :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-button-color="#4f46e5"
  data-button-text-color="#ffffff"
  async
></script>

Ces deux attributs ne stylisent que le bouton flottant du widget lui-même. Lorsque vous vous liez à votre propre élément avec data-trigger, le lanceur hérite du style de cet élément, donc ils n'ont aucun effet.

Personnaliser le point non lu

Le point non lu est rouge (#e5484d) et activé par défaut. Recolorez-le avec data-unread-color (une valeur hexadécimale ou un nom de couleur CSS), ou désactivez-le avec data-unread="off" :

<!-- Recolor the dot -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread-color="#7c3aed" async></script>

<!-- Turn the dot off -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread="off" async></script>

Désactiver le point conserve le lanceur et la fenêtre modale. Cela ne supprime que l'indicateur. La section suivante explique comment l'état « vu » est suivi.

Le point non lu

Le widget conserve un indicateur non lu par visiteur. Il compare l'id de l'entrée la plus récente à une valeur dans le localStorage du navigateur (une clé par projet). Lorsqu'ils diffèrent, un point apparaît sur le lanceur ; ouvrir la fenêtre modale marque l'entrée comme vue et efface le point jusqu'à la prochaine mise à jour publiée.

Comme l'état vit dans localStorage, il est propre à chaque navigateur et à chaque visiteur. Il n'y a ni compte ni suivi, et l'effacement des données du site le réinitialise. Un visiteur avec un navigateur neuf voit le point une fois, puis plus jamais jusqu'à ce que vous publiiez quelque chose de nouveau.

Exemples

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-position="bottom-left"
  data-unread-color="#22c55e"
  async
></script>

Content-Security-Policy

Si votre propre site envoie un Content-Security-Policy strict, autorisez votre origine *.jamdesk.app dans trois directives, sinon le widget ne fait silencieusement rien :

Content-Security-Policy:
  script-src  https://acme.jamdesk.app;
  frame-src   https://acme.jamdesk.app;
  connect-src https://acme.jamdesk.app;

• script-src charge widget.js.
• frame-src affiche l'iframe de la fenêtre modale.
• connect-src récupère les métadonnées du changelog pour le point non lu.

Si vous en oubliez une, il n'y a pas de bannière d'erreur : le lanceur n'apparaît tout simplement pas, ou la fenêtre modale reste vide. Vérifiez la console de votre navigateur pour des violations CSP si le widget ne s'affiche pas.

Sites protégés par mot de passe

Et ensuite ?