Imágenes
Añade imágenes a tu documentación con sintaxis de markdown, control de dimensiones, leyendas y compatibilidad con modo claro/oscuro.
Jamdesk renderiza las imágenes con esquinas redondeadas y un espaciado consistente. Coloca los archivos en tu directorio /images y haz referencia a ellos con markdown estándar.
Las capturas de pantalla muestran la interfaz en inglés.
Markdown estándar
Usa la sintaxis habitual :
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
Añade =WIDTHxHEIGHT 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 resulta ú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 añadirle 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 en su interior, no solo con imágenes.
Modo claro/oscuro
Los sitios de documentación a menudo necesitan variantes distintas de imagen para cada esquema de color: un logotipo sobre fondo blanco se ve 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=mo97v0f0"
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 también funcione 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=mo97v0f0" alt="Company logo" />
</picture>El enfoque <picture> respeta la configuración de esquema de color del sistema operativo. El atributo srcDark, en cambio, responde al interruptor de tema de Jamdesk, que suele ser lo que quieres en documentación.
Formatos admitidos
| Formato | Ideal para | Notas |
|---|---|---|
| PNG | Capturas de pantalla, capturas de UI | Calidad sin pérdida, admite transparencia. Archivos más grandes. |
| JPEG | Fotografías | Buena compresión, sin soporte para 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 simples | Puede crecer rápidamente. Considera bucles cortos de .mp4 para cualquier cosa de 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 soporta: no hace falta recurrir a PNG.
Buenas prácticas
El texto alternativo cumple dos funciones: los lectores de pantalla lo usan para accesibilidad, y aparece como marcador de posición cuando la imagen no se carga. Describe lo que realmente muestra la imagen.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Para imágenes decorativas que no aportan información (patrones de fondo, separadores), usa texto alternativo vacío: .
Las imágenes pesadas ralentizan la carga de las páginas, sobre todo 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 una de estas herramientas antes de hacer commit.
O deja que Jamdesk se encargue en tiempo de 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 anchos distintos quedan desordenadas. Elige un ancho de captura estándar (1200px funciona bien) y úsalo en toda tu documentación. Jamdesk escala las imágenes automáticamente para ajustarlas al área de contenido, por lo que unas 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 las mantiene fáciles de encontrar a medida que crece tu documentación:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
Referéncialas con la ruta completa desde la raíz de tu proyecto:
Evita los espacios en los nombres de archivo de imagen. Usa guiones en su lugar: api-response.webp, no api response.webp.