Insertar una página

Tu changelog ya vive en tu documentación. Esta guía coloca un disparador «What's new?» dentro de tu propio producto: un botón o un lanzador flotante que abre esas mismas entradas en una ventana modal, con un punto que marca las actualizaciones no leídas por visitante. Pegas una sola etiqueta <script>; Jamdesk aloja y versiona el widget.

Las capturas de pantalla muestran la interfaz en inglés.

El changelog es el caso habitual, y aquel en torno al cual se construye el punto de no leído. Sin embargo, el mismo widget puede abrir cualquier página de la documentación en el modal. Apunta data-page allí donde una página enfocada y contextual ayude (consulta Dirige el modal a cualquier página).

Pruébalo en vivo

Esta página ejecuta el widget real. Haz clic abajo y el mismo modal que reciben tus visitantes se abre aquí mismo, cargando el propio changelog de este sitio:

Ese botón en vivo es el componente MDX <Widget>, la forma más simple de insertar el widget en una página de documentación de Jamdesk: es una sola etiqueta, no requiere script y resuelve tu sitio automáticamente. El fragmento <script> de abajo es para el otro caso, insertar el widget en tu propio producto o aplicación, donde los componentes MDX no se ejecutan. Es el mismo widget y el mismo modal en ambos casos; el resto de esta página trata el script.

Requisitos previos

• Un sitio de Jamdesk publicado en su subdominio *.jamdesk.app (el widget siempre carga desde ahí, incluso si también sirves la documentación en un dominio personalizado).
• Una página de changelog construida con entradas <Update> que tengan rss: true en su frontmatter (consulta Actívalo con rss: true).

Inicio rápido

Abre tu dashboard, ve a Integrations → What's New widget, define la página y las opciones del lanzador, y copia el fragmento generado. Se ve así:

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

Pégalo en el HTML de tu aplicación, antes de la etiqueta de cierre </body>. Al cargar, añade un lanzador flotante What's new en la esquina. Al hacer clic, abre tu changelog en una ventana modal; aparece un punto de no leído cuando hay una entrada que el visitante no ha visto.

Fija una versión o aloja tu propia copia

El widget es de código abierto, y el fragmento alojado de arriba siempre sirve la última versión, lo cual es la opción correcta por defecto para la mayoría de los sitios. Cuando prefieras congelar una versión conocida o servir el archivo tú mismo, el repositorio jamdesk-widget ofrece otras dos formas de cargarlo.

Fija una versión con jsDelivr. Carga un lanzamiento etiquetado desde el CDN y los bytes nunca cambian bajo tus pies:

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

Aloja tu propia copia. Descarga widget.js desde el último lanzamiento y sírvelo desde tu propio origen. Esto ayuda cuando una política script-src estricta descarta los scripts de terceros.

En cualquier caso, define data-base con tu origen *.jamdesk.app: el fragmento alojado lo lee desde la propia URL del script, pero un CDN o tu propio servidor no pueden hacerlo. Cada lanzamiento publica un hash de Subresource Integrity para que puedas fijar los bytes exactos. El README del repositorio recorre las tres formas de instalación.

Actívalo con rss: true

El widget lee la entrada más reciente del mismo feed que alimenta tu RSS, así que una página solo alimenta al widget cuando su frontmatter define 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>

Sin rss: true, el widget carga pero no muestra entradas y el lanzador permanece oculto. Una página de documentación que simplemente demuestra el componente <Update> (sin rss: true) queda correctamente excluida, de modo que una fecha de demostración nunca enciende el punto.

Configura el snippet

Cada opción es un atributo data- en la etiqueta script. La tarjeta del dashboard los escribe por ti, pero también puedes editar el fragmento a mano.

Dirige el modal a cualquier página

data-page abre cualquier ruta de tu sitio de documentación, no solo /changelog. El modal muestra la página que nombres, como un anuncio puntual o una nota de migración, despojada del chrome del sitio. Apúntalo allí donde una página enfocada y contextual ayude:

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

Dos comportamientos siguen ligados al feed de tu changelog, así que tenlos en cuenta cuando la página no sea un changelog:

• El punto de no leído sigue la entrada más reciente de tu changelog, no la página del modal. Define data-unread="off" cuando el modal abra otra cosa, o el punto se encenderá por actualizaciones del changelog que el visitante nunca ve ahí.
• El lanzador flotante solo aparece automáticamente una vez que tu changelog tiene una entrada (consulta Actívalo con rss: true). Para insertar una página en un sitio sin changelog, vincúlate a tu propio elemento con data-trigger. Tu elemento se muestra de todos modos.

Modos del lanzador

Cuando te vinculas a tu propio elemento, el widget añade el punto de no leído a ese elemento y nunca renderiza un botón flotante (por lo que data-position y data-label dejan de aplicarse):

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

Define el tamaño del modal

El modal se abre a 560 × 680 px. Define data-width y data-height para cambiarlo. Un número simple se interpreta como píxeles, o usa cualquier valor px, vw, vh, rem, em o %:

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

Ambas dimensiones tienen un tope de forma responsiva (92vw de ancho, 86vh de alto), así que un tamaño grande sigue cabiendo en un teléfono. Un valor no reconocido recurre al predeterminado. Las esquinas tienen por defecto un radio de 12px; define data-radius (cualquier longitud CSS) para hacerlas más cuadradas o más redondeadas.

Estiliza el botón del lanzador

El lanzador flotante es una píldora oscura por defecto. Recolóralo con data-button-color (fondo) y data-button-text-color (texto), cada uno un valor hexadecimal o un nombre de color 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>

Estos dos atributos solo estilizan el propio botón flotante del widget. Cuando te vinculas a tu propio elemento con data-trigger, el lanzador hereda el estilo de ese elemento, así que no tienen efecto.

Personaliza el punto de no leído

El punto de no leído es rojo (#e5484d) y está activado por defecto. Recolóralo con data-unread-color (un valor hexadecimal o un nombre de color CSS), o desactívalo con 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>

Desactivar el punto conserva el lanzador y el modal. Solo elimina el indicador. La siguiente sección explica cómo se rastrea el estado «visto».

El punto de no leído

El widget mantiene un indicador de no leído por visitante. Compara el id de la entrada más reciente con un valor en el localStorage del navegador (una clave por proyecto). Cuando difieren, aparece un punto en el lanzador; abrir el modal marca la entrada como vista y borra el punto hasta que se publique la próxima actualización.

Como el estado vive en localStorage, es por navegador y por visitante. No hay cuenta ni seguimiento, y borrar los datos del sitio lo reinicia. Un visitante con un navegador nuevo ve el punto una vez, y luego no vuelve a verlo hasta que publiques algo nuevo.

Ejemplos

<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 tu propio sitio envía un Content-Security-Policy estricto, permite tu origen *.jamdesk.app en tres directivas, o el widget no hará nada silenciosamente:

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

• script-src carga widget.js.
• frame-src renderiza el iframe del modal.
• connect-src obtiene los metadatos del changelog para el punto de no leído.

Si omites una, no hay banner de error: el lanzador simplemente no aparecerá o el modal quedará en blanco. Revisa la consola de tu navegador en busca de violaciones de CSP si el widget no se muestra.

Sitios protegidos con contraseña

¿Qué sigue?