Incrustar una página

Tu changelog ya vive en tu documentación. Esta guía coloca un disparador de "Novedades" 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 una etiqueta <script>; Jamdesk aloja y versiona el widget.

El changelog es el caso común, y el que da origen al 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 a donde una página enfocada y en contexto ayude (consulta Apunta el modal a cualquier página).

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

Pruébalo en vivo

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

Ese botón en vivo es el componente MDX <Widget>, la forma más simple de incrustar 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, 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 de Jamdesk publicado en su subdominio *.jamdesk.app (el widget siempre carga desde ahí, incluso si también sirves documentación en un dominio personalizado).
• Una página de changelog construida a partir de entradas <Update> con rss: true en su frontmatter (consulta Habilítalo 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. 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 app, 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 un modal; aparece un punto de no leído cuando hay una entrada que el visitante no ha visto.

Fija una versión o autoalójalo

El widget es de código abierto, y el fragmento alojado de arriba siempre sirve la última versión, que es la opción correcta por defecto para la mayoría de sitios. Cuando prefieras fijar 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 una versión etiquetada desde el CDN y los bytes nunca cambian bajo ti:

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

Autoalójalo. Descarga widget.js desde el último release y sírvelo desde tu propio origen. Esto ayuda cuando una política script-src estricta descarta scripts de terceros.

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

Habilítalo 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 solo demuestra el componente <Update> (sin rss: true) queda correctamente excluida, así que una fecha de demostración nunca activa el punto.

Configura el fragmento

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

Apunta el modal a cualquier página

data-page abre cualquier ruta de tu sitio de documentación, no solo /changelog. El modal renderiza la página que indiques, como un único anuncio o una nota de migración, despojada de su interfaz general del sitio. Apúntalo donde una página enfocada y en contexto 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 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 del modal. Define data-unread="off" cuando el modal abra otra cosa, o el punto se activará 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 Habilítalo con rss: true). Para incrustar una página en un sitio sin changelog, vincúlala a tu propio elemento con data-trigger. Tu elemento se muestra de todos modos.

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 (así 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>

Ajusta el tamaño del modal

El modal se abre a 560 × 680 px. Define 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 tienen un límite responsivo (92vw de ancho, 86vh de alto), así que un tamaño grande sigue cabiendo en un teléfono. Un valor no reconocido recae en el predeterminado. Las esquinas por defecto tienen un radio de 12px; define data-radius (cualquier longitud CSS) para cuadrarlas o redondearlas más.

Personaliza el botón del lanzador

El lanzador flotante es una píldora oscura por defecto. Recolorea 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 dan estilo al botón flotante propio del widget. Cuando 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. Recolorea 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; al abrir el modal se marca la entrada como vista y se 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 rastreo, y borrar los datos del sitio lo reinicia. Un visitante en 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>

<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 dejará de funcionar 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 habrá aviso 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?