Imágenes
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 :
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:
Indica solo una dimensión y la otra se escala proporcionalmente:
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 <Frame> para añadir un borde y un pie de foto debajo:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
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:
<img
src="/_jd/images/logo-light.webp?v=mp4qj7v2"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>El navegador carga únicamente la imagen que coincide con el esquema de color actual.
El elemento HTML <picture>
Si necesitas HTML estándar que funcione también fuera de Jamdesk, usa <picture> con una media query:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mp4qj7v2" alt="Company logo" />
</picture>El enfoque <picture> 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.
{/* 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 y TinyPNG 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 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:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonRefiérete a ellas con la ruta completa desde la raíz de tu proyecto:
Evita espacios en los nombres de archivo de las imágenes. Usa guiones en su lugar: api-response.webp, no api response.webp.