Incrustar una página

Tu changelog ya vive en tu documentación. Esta guía coloca un disparador "¿Qué hay de nuevo?" dentro de tu propio producto: un botón o lanzador flotante que abre esas mismas entradas en un modal, con un punto que marca las actualizaciones no leídas por visitante. Pegas un tag <script>; Jamdesk aloja y versiona el widget.

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

El changelog es el caso más común, y para el que está construido el punto de no leído. Sin embargo, el mismo widget puede abrir cualquier página de documentación en el modal — apunta data-page donde una página enfocada y contextual sea útil (consulta Apuntar el modal a cualquier página).

Pruébalo en vivo

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

Ese botón en vivo es el componente MDX <Widget>, la forma más sencilla de incrustar el widget en una página de documentación de Jamdesk: un tag, sin script, y resuelve tu sitio automáticamente. El fragmento <script> que aparece a continuación es para el otro caso: incrustar el widget en tu propio producto o app, donde los componentes MDX no se ejecutan. El mismo widget y modal en ambos casos; el resto de esta página cubre el script.

Requisitos previos

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

Inicio rápido

Abre tu dashboard, ve a Settings → What's New widget, configura la página y las opciones del lanzador, y copia el fragmento generado. Tiene este aspecto:

<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 app, antes del tag de cierre </body>. Al cargar, añade un lanzador flotante What's new en la esquina. Al hacer clic abre tu changelog en un modal; aparece un punto de no leído cuando hay una entrada que el visitante no ha visto.

Fijar una versión o alojar por tu cuenta

El widget es de código abierto, y el fragmento alojado anterior siempre sirve la última versión — la opción correcta para la mayoría de los sitios. Si prefieres congelar una versión conocida o servir el archivo tú mismo, el repositorio jamdesk-widget ofrece dos formas más de cargarlo.

Fijar una versión con jsDelivr. Carga una versión etiquetada 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>

Alojar por tu cuenta. Descarga widget.js de la última versión y sírvelo desde tu propio origen. Esto ayuda cuando una política estricta de script-src excluye scripts de terceros.

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

Activar con rss: true

El widget lee la entrada más reciente del mismo feed que alimenta tu RSS, por lo que una página solo alimenta el widget cuando su frontmatter establece 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.

Configurar el fragmento

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

Apuntar el modal a cualquier página

data-page abre cualquier ruta en tu sitio de documentación, no solo /changelog. El modal renderiza cualquier página que indiques, desprovista del cromo del sitio — un anuncio concreto, una guía de inicio, una nota de migración. Apúntalo donde una página enfocada y contextual sea útil:

<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 están vinculados a tu feed de changelog, así que tenlos en cuenta cuando la página no sea un changelog:

• El punto de no leído rastrea la entrada más reciente de tu changelog, no la página en el modal. Establece data-unread="off" cuando el modal abre otra cosa, o el punto se iluminará por actualizaciones del changelog que el visitante nunca verá allí.
• El lanzador flotante solo aparece automáticamente cuando tu changelog tiene una entrada (consulta Activar con rss: true). Para incrustar una página en un sitio sin changelog, vincula a tu propio elemento con data-trigger — tu elemento se muestra independientemente.

Modos del lanzador

Cuando 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 ya no aplican):

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

Dimensionar el modal

El modal se abre a 560 × 680 px. Establece data-width y data-height para cambiarlo. Un número sin unidad 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 están limitadas de forma adaptativa (92vw de ancho, 86vh de alto), por lo que un tamaño grande sigue ajustándose en un teléfono. Un valor no reconocido vuelve al predeterminado. Las esquinas tienen por defecto un radio de 12px; establece data-radius (cualquier longitud CSS) para hacerlas más cuadradas o más redondeadas.

Estilizar el botón del lanzador

El lanzador flotante es una píldora oscura por defecto. Cambia su color con data-button-color (fondo) y data-button-text-color (texto), cada uno como valor hex o 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 botón flotante propio del widget. Cuando vinculas a tu propio elemento con data-trigger, el lanzador hereda el estilo de ese elemento, por lo que no tienen efecto.

Personalizar el punto de no leído

El punto de no leído es rojo (#e5484d) y está activado por defecto. Cambia su color con data-unread-color (un valor hex o 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 mantiene 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 siguiente 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 en un navegador nuevo ve el punto una vez, y luego no lo verá de nuevo 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>

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

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 falta una directiva, no aparece ningún banner de error: el lanzador simplemente no aparece o el modal queda en blanco. Revisa la consola del navegador en busca de violaciones de CSP si el widget no se muestra.

Sitios protegidos con contraseña

¿Qué sigue?