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.

Aunque no se pueda incrustar, el enlace funciona bien en GitHub: si el PDF está dentro del repositorio, al abrirlo GitHub lo muestra renderizado en su propio visor, sin necesidad de descargarlo. La única limitación es que los enlaces que haya dentro del PDF no se pueden pulsar desde ese visor.

Si quieres que el enlace sea más visible, puedes combinarlo con una imagen de portada del documento, igual que se hace con los vídeos. Lo explicamos en cómo usar una imagen como enlace.

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.

Insertar un PDF en Obsidian

Obsidian sí permite ver un PDF dentro de una nota, sin HTML, con su sintaxis propia de inserción. Basta con añadir un signo de exclamación delante del enlace interno al archivo:

![[Documento.pdf]]

La inserción admite dos opciones que se añaden al nombre del archivo. Con #page= abres el PDF directamente en una página concreta, y con #height= fijas la altura del visor en píxeles:

![[Documento.pdf#page=3]]
![[Documento.pdf#height=400]]

Ten en cuenta que esta sintaxis es exclusiva de Obsidian y de algunas herramientas compatibles. Si abres la nota en otro editor de Markdown, verás el texto tal cual, sin el PDF.

Convertir el PDF a Markdown

A veces lo que necesitas no es mostrar el PDF, sino su contenido: citar un fragmento, reutilizar una tabla o pasárselo a un chatbot de IA. En ese caso tiene más sentido convertir el PDF a Markdown que incrustarlo.

Herramientas como MarkItDown, de Microsoft, extraen el texto de un PDF y lo devuelven en Markdown conservando encabezados, listas y tablas. Explicamos cómo instalarla y usarla en cómo usar MarkItDown con Claude. El resultado es texto que puedes editar, buscar y versionar, algo imposible con un PDF incrustado.

Y al revés: de Markdown a PDF

Si lo que buscas es lo contrario, es decir, entregar en PDF un documento que has escrito en Markdown, no necesitas incrustar nada. Puedes generar el PDF directamente con nuestro conversor de Markdown a PDF, que funciona en el navegador sin instalar nada, o con Pandoc si quieres automatizar la conversión.

Esto ha sido todo.