Imágenes
Agrega imágenes a tu documentación con sintaxis markdown, controles de dimensiones, leyendas y soporte para modo claro/oscuro.
Jamdesk renderiza imágenes con esquinas redondeadas y espaciado consistente. Coloca los archivos en tu directorio /images y referéncialos con markdown estándar.
Las capturas de pantalla muestran la interfaz en inglés.
Las capturas de pantalla de esta página muestran la interfaz en inglés. La funcionalidad es idéntica en todos los idiomas.
Markdown estándar
Usa la sintaxis familiar :
Las rutas comienzan desde la raíz de tu proyecto. Una imagen en your-docs/images/screenshot.webp se referencia como /images/screenshot.webp.
Dimensiones de imagen
Agrega =ANCHOxALTO después de la URL de la imagen (separado por un espacio) para controlar el tamaño:
Establece solo una dimensión y la otra se escala proporcionalmente:
Esto es útil cuando quieres una columna consistente de capturas de pantalla con el mismo ancho, o necesitas reducir una imagen de alta resolución a un tamaño de visualización razonable.
Leyendas
Envuelve una imagen en el componente <Frame> para agregar un borde y una leyenda debajo:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame dibuja un borde sutil alrededor de la imagen y coloca el texto de la leyenda debajo. Funciona con cualquier contenido dentro, no solo imágenes.
Modo claro/oscuro
Los sitios de documentación a menudo necesitan variantes de imagen diferentes para cada esquema de color — un logotipo sobre fondo blanco se ve mal en modo oscuro.
El atributo srcDark
El enfoque más simple. Jamdesk intercambia la fuente de la imagen según el tema activo:
<img
src="/_jd/images/logo-light.webp?v=mof559f5"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>El navegador carga solo la imagen que coincide con el esquema de color actual.
El elemento HTML <picture>
Si necesitas HTML estándar que funcione fuera de Jamdesk también, 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=mof559f5" alt="Company logo" />
</picture>El enfoque <picture> respeta la configuración del esquema de color del sistema operativo. El atributo srcDark responde al selector de tema de Jamdesk, lo cual es generalmente lo que quieres para la documentación.
Formatos soportados
| Formato | Mejor para | Notas |
|---|---|---|
| PNG | Capturas de pantalla, capturas de UI | Calidad sin pérdidas, 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 pequeño. |
| GIF | Animaciones simples | Puede crecer rápidamente. Considera bucles cortos .mp4 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 — no necesitas PNG.
Mejores prácticas
El texto alternativo tiene dos propósitos: los lectores de pantalla lo usan para la accesibilidad, y aparece como marcador de posición cuando la imagen no carga. Describe lo que la imagen muestra realmente.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Para imágenes decorativas que no agregan información (patrones de fondo, separadores), usa texto alternativo vacío: .
Las imágenes pesadas ralentizan la carga de páginas, especialmente en conexiones móviles. Tamaños objetivo:
- Capturas de pantalla/UI: PNG o WebP, menos de 500KB
- Fotos: JPEG o WebP, menos de 200KB
- Iconos y diagramas: SVG siempre que sea posible
Squoosh y TinyPNG comprimen imágenes sin pérdida visible de calidad. Pasa las capturas de pantalla por alguno de estos antes de hacer commit.
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 subas se optimizará en cada build.
Las capturas de pantalla que saltan entre diferentes anchos se ven desordenadas. Elige un ancho de captura estándar (1200px 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 las dimensiones de origen consistentes producen resultados renderizados consistentes.
Organización de archivos
Agrupa las imágenes en subdirectorios que reflejen la estructura de tu contenido. Esto mantiene las cosas localizables a medida que crece tu documentación:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonReferencíalos con la ruta completa desde la raíz de tu proyecto:
Evita espacios en los nombres de archivos de imagen. Usa guiones en su lugar: api-response.webp, no api response.webp.