Cómo insertar un PDF en un documento Markdown

Insertar un archivo PDF dentro de un documento Markdown es una necesidad habitual en informes técnicos, manuales de usuario, documentación legal y cualquier proyecto donde el PDF sea el formato oficial de referencia. El problema es que Markdown estándar no contempla la inserción de PDFs: lo más cercano es un enlace al archivo, y para visualizarlo en línea hace falta recurrir a HTML.

A continuación verás las técnicas más usadas, desde el simple enlace hasta la incrustación con iframe, embed u object.

Enlazar a un archivo PDF

La opción más portátil y compatible con cualquier procesador de Markdown es enlazar al PDF con la sintaxis estándar de enlace. Al hacer clic, el navegador abrirá el archivo en su visor integrado de PDF (o lo descargará, según la configuración del usuario).

En el siguiente ejemplo enlazamos a un PDF guardado en el repositorio:

[Descargar el manual en PDF](./docs/manual.pdf)

Es la opción recomendada en archivos README de GitHub o GitLab, donde no se permite incrustar PDFs y cualquier intento con HTML será filtrado.

Incrustar un PDF con iframe

Si controlas el entorno de publicación (un blog propio, un sitio estático con Hugo, Astro o Next.js, una documentación interna) y permite HTML, lo más sencillo es usar un <iframe> apuntando al archivo PDF. El navegador renderizará el visor de PDF integrado dentro de la página.

En el siguiente ejemplo incrustamos un PDF con <iframe>:

<iframe src="/docs/manual.pdf" width="100%" height="600px"></iframe>

Es la técnica más usada por su simplicidad y porque funciona en la mayoría de navegadores modernos. El usuario podrá hacer scroll, zoom y descargar el archivo desde los controles del visor.

Incrustar un PDF con embed

La etiqueta <embed> es una alternativa más antigua a <iframe>, también soportada en todos los navegadores. La principal diferencia es que <embed> está pensada específicamente para incrustar contenido externo como PDFs, vídeos o plugins.

En el siguiente ejemplo usamos <embed> con el tipo MIME correspondiente:

<embed src="/docs/manual.pdf" type="application/pdf" width="100%" height="600px" />

A efectos prácticos el resultado es idéntico al de un <iframe>. Elige una u otra según tu preferencia o las restricciones de la plataforma.

Incrustar un PDF con object

La etiqueta <object> ofrece una ventaja adicional sobre <iframe> y <embed>: permite mostrar un contenido alternativo cuando el navegador no es capaz de renderizar el PDF (por ejemplo, en algunos móviles antiguos o entornos restringidos).

En el siguiente ejemplo combinamos <object> con un enlace de respaldo:

<object data="/docs/manual.pdf" type="application/pdf" width="100%" height="600px">
  <p>El navegador no puede mostrar el PDF. <a href="/docs/manual.pdf">Descárgalo aquí</a>.</p>
</object>

Es la opción más robusta cuando la accesibilidad es una prioridad.

Plataformas que no admiten ninguna de las anteriores

GitHub, GitLab, Bitbucket, foros de Discourse y la mayoría de gestores de contenido filtran las etiquetas <iframe>, <embed> y <object> por motivos de seguridad. En esos entornos no podrás incrustar el PDF directamente y tendrás que conformarte con un enlace.

Como alternativa, puedes subir el PDF a un servicio externo como Google Drive, Dropbox o un visor especializado como DocDroid, y enlazar a la URL que ofrezcan. Algunos de esos servicios proporcionan un código de incrustación específico que sí pasa los filtros de seguridad de ciertas plataformas, así que vale la pena revisar lo que ofrecen antes de descartar la opción.

Esto ha sido todo.