---
title: Imágenes
description: Añade imágenes a tu documentación con sintaxis Markdown, control de dimensiones, pies de foto y soporte para modo claro/oscuro.
---
Jamdesk renderiza las imágenes con esquinas redondeadas y un espaciado uniforme. Coloca los archivos en tu directorio `/images` y refiérete a ellos con Markdown estándar.
Las capturas de pantalla muestran la interfaz en inglés.
## Markdown estándar
Usa la sintaxis familiar ``:
```markdown
```
Las rutas parten desde la raíz de tu proyecto. Una imagen en `your-docs/images/screenshot.webp` se referencia como `/images/screenshot.webp`.
## Dimensiones de imagen
Añade `=WIDTHxHEIGHT` después de la URL de la imagen (separado por un espacio) para controlar el tamaño:
```markdown
```
Indica solo una dimensión y la otra se escala proporcionalmente:
```markdown
```
Esto es útil cuando quieres una columna uniforme de capturas al mismo ancho, o necesitas reducir una imagen de alta resolución a un tamaño de visualización razonable.
## Pies de foto
Envuelve una imagen en el componente `` para añadir un borde y un pie de foto debajo:
```mdx
```
`Frame` dibuja un borde sutil alrededor de la imagen y coloca el texto del pie de foto debajo. Funciona con cualquier contenido en su interior, no solo imágenes.
## Modo claro/oscuro
Los sitios de documentación suelen necesitar variantes de imagen distintas para cada esquema de color -- un logotipo sobre fondo blanco queda mal en modo oscuro.
### El atributo `srcDark`
El enfoque más sencillo. Jamdesk intercambia la fuente de la imagen según el tema activo:
```mdx
```
El navegador carga únicamente la imagen que coincide con el esquema de color actual.
### El elemento HTML ``
Si necesitas HTML estándar que funcione también fuera de Jamdesk, usa `` con una media query:
```mdx
```
El enfoque `` respeta la configuración de esquema de color del sistema operativo. El atributo `srcDark` responde al selector de tema de Jamdesk, que es lo que generalmente querrás para la documentación.
## Formatos compatibles
| Formato | Ideal para | Notas |
|--------|----------|-------|
| PNG | Capturas de pantalla, capturas de interfaz | Calidad sin pérdida, admite transparencia. Archivos más grandes. |
| JPEG | Fotografías | Buena compresión, sin soporte de transparencia. |
| SVG | Iconos, diagramas, logotipos | Formato vectorial -- escala a cualquier tamaño sin pérdida de calidad. Tamaño de archivo mínimo. |
| GIF | Animaciones sencillas | Puede crecer rápido. Considera bucles `.mp4` cortos para más de unos pocos fotogramas. |
| WebP | Uso general | Más pequeño que PNG y JPEG con calidad comparable. Funciona en todos los navegadores modernos. |
WebP ofrece la mejor relación tamaño-calidad para la mayoría de las imágenes de documentación. Si necesitas transparencia, WebP también la admite -- sin necesidad de PNG.
## Mejores prácticas
El texto alternativo cumple dos propósitos: los lectores de pantalla lo usan para accesibilidad, y aparece como marcador de posición cuando la imagen no se carga. Describe lo que la imagen realmente muestra.
```markdown
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
```
Para imágenes decorativas que no añaden información (patrones de fondo, separadores), usa texto alternativo vacío: ``.
Las imágenes pesadas ralentizan la carga de la página, especialmente en conexiones móviles. Tamaños objetivo:
- **Capturas/Interfaz:** PNG o WebP, menos de 500 KB
- **Fotos:** JPEG o WebP, menos de 200 KB
- **Iconos y diagramas:** SVG siempre que sea posible
[Squoosh](https://squoosh.app) y [TinyPNG](https://tinypng.com) comprimen imágenes sin pérdida de calidad visible. Pasa las capturas por alguno de ellos antes de confirmar los cambios.
O deja que Jamdesk lo gestione en el momento del build. Activa la [conversión automática a WebP](/es/builds/image-optimization) en tu `docs.json` y cualquier PNG o JPG que confirmes se optimizará en cada build.
Las capturas que saltan entre distintos anchos quedan desordenadas. Elige un ancho de captura estándar (1200 px funciona bien) y úsalo en toda tu documentación. Jamdesk escala las imágenes para ajustarse al área de contenido automáticamente, por lo que unas dimensiones de origen uniformes producen resultados renderizados uniformes.
## Organización de archivos
Agrupa las imágenes en subdirectorios que reflejen la estructura de tu contenido. Esto facilita encontrarlas a medida que crece tu documentación:
```bash
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
```
Refiérete a ellas con la ruta completa desde la raíz de tu proyecto:
```markdown
```
Evita espacios en los nombres de archivo de las imágenes. Usa guiones en su lugar: `api-response.webp`, no `api response.webp`.
## ¿Qué sigue?
Incrusta vídeos y Shorts de YouTube
Archivos MP4 y WebM locales
Vimeo, CodePen, Figma y más
```
El navegador carga únicamente la imagen que coincide con el esquema de color actual.
### El elemento HTML `