Intégrer une page

Votre changelog vit déjà dans vos docs. Ce guide place un déclencheur « Quoi de neuf ? » dans votre propre produit : un bouton ou un lanceur flottant qui ouvre ces mêmes entrées dans une modale, avec un point qui marque les mises à jour non lues par visiteur. Vous collez une balise <script> ; Jamdesk héberge et versionne le widget.

Le changelog est le cas courant, et celui autour duquel le point non lu est construit. Le même widget peut toutefois ouvrir n'importe quelle page de docs dans la modale. Pointez data-page là où une page ciblée et contextuelle aide (voir Pointer la modale vers n'importe quelle page).

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

L'essayer en direct

Cette page fait tourner le vrai widget. Cliquez ci-dessous et la même modale que vos visiteurs obtiennent s'ouvre ici même, en chargeant le changelog de ce site :

Ce bouton en direct est le composant MDX <Widget>, la façon la plus simple d'intégrer le widget dans une page de docs Jamdesk : c'est une seule balise, sans script requis, et elle résout automatiquement votre site. Le snippet <script> ci-dessous est pour l'autre cas, intégrer le widget dans votre propre produit ou appli, où les composants MDX ne s'exécutent pas. Même widget et même 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 vos docs sur un domaine personnalisé).
• Une page de changelog construite à partir d'entrées <Update> avec rss: true dans son frontmatter (voir Activer avec rss: true).

Démarrage rapide

Ouvrez votre dashboard, allez dans Settings → What's New widget, définissez la page et les options du lanceur, et copiez le snippet généré. Il ressemble à ceci :

<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 appli, 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 modale ; un point non lu apparaît quand 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 le snippet hébergé ci-dessus sert toujours la dernière version, ce qui est le bon défaut pour la plupart des sites. Quand 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.

Épingler 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>

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

Dans les deux cas, définissez data-base sur votre origine *.jamdesk.app : le snippet 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 pour é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 docs qui démontre simplement le composant <Update> (sans rss: true) est correctement exclue, donc une date de démo n'allume jamais le point.

Configurer le snippet

Chaque option est un attribut data- sur la balise script. La carte du dashboard les écrit pour vous, mais vous pouvez aussi éditer le snippet à la main.

Pointer la modale vers n'importe quelle page

data-page ouvre n'importe quel chemin de votre site de docs, pas seulement /changelog. La modale affiche la page que vous nommez, comme une annonce unique ou une note de migration, dépouillée de l'habillage du site. Pointez-la là où une page ciblée et contextuelle aide :

<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 à votre flux de changelog, à garder en tête quand 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 dans la modale. Définissez data-unread="off" quand la modale ouvre autre chose, sinon le point s'allume pour des mises à jour de changelog que le visiteur ne voit jamais là.
• Le lanceur flottant n'apparaît automatiquement que lorsque 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 quoi qu'il arrive.

Modes du lanceur

Quand vous vous liez à votre propre élément, le widget ajoute le point non lu à cet élément et n'affiche jamais de bouton flottant (donc data-position et data-label ne s'appliquent 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>

Dimensionner la modale

La modale s'ouvre à 560 × 680 px. Définissez data-width et data-height pour la modifier. Un nombre nu est lu 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), donc une grande taille tient quand même sur un téléphone. Une valeur non reconnue revient au défaut. Les coins ont par défaut un rayon de 12px ; définissez data-radius (n'importe quelle longueur CSS) pour les carrer ou les arrondir davantage.

Styliser le bouton du lanceur

Le lanceur flottant est une pilule sombre par défaut. Recolorez-le avec data-button-color (fond) et data-button-text-color (texte), chacun une valeur hex 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 propre au widget. Quand 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 hex 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 modale. Cela ne fait que retirer l'indicateur. La section suivante explique comment l'état « vu » est suivi.

Le point non lu

Le widget maintient 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). Quand ils diffèrent, un point apparaît sur le lanceur ; ouvrir la modale marque l'entrée comme vue et efface le point jusqu'à la prochaine mise à jour publiée.

Comme l'état vit dans le localStorage, il est propre à chaque navigateur et à chaque visiteur. Il n'y a ni compte ni suivi, et effacer les données du site le réinitialise. Un visiteur avec un navigateur neuf voit le point une fois, puis plus 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>

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

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-label="Release notes"
  data-unread="off"
  async
></script>

Content-Security-Policy

Si votre propre site envoie une Content-Security-Policy stricte, 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 modale.
• connect-src récupère les métadonnées du changelog pour le point non lu.

En manquer une et il n'y a pas de bannière d'erreur : le lanceur n'apparaît simplement pas ou la 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 ?