Imágenes
Aprende cómo Jamdesk gestiona tamaño, subtítulos, variantes claro/oscuro y formatos de imagen para mantener la documentación nítida y accesible.
Jamdesk renderiza imágenes con bordes redondeados y espaciado uniforme. 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
Agrega =ANCHOxALTO después de la URL de la imagen (separado por un espacio) para controlar el tamaño:
Define solo una dimensión y la otra se escala proporcionalmente:
Esto resulta útil cuando quieres una columna uniforme de capturas de pantalla del mismo ancho, o necesitas reducir una imagen de alta resolución a un tamaño de visualización razonable.
Subtítulos
Envuelve una imagen en el componente <Frame> para agregar un borde y un subtítulo debajo:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame dibuja un borde sutil alrededor de la imagen y coloca el texto del subtítulo debajo. Funciona con cualquier contenido dentro de él, no solo imágenes.
Modo claro/oscuro
Los sitios de documentación suelen necesitar variantes de imagen distintas para cada esquema de color: un logo 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=mrtvmucv"
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 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=mrtvmucv" 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, que suele ser lo que quieres para la documentación.
Formatos compatibles
| Formato | Ideal para | Notas |
|---|---|---|
| PNG | Capturas de pantalla, interfaces | Calidad sin pérdida, admite transparencia. Archivos más grandes. |
| JPEG | Fotografías | Buena compresión, sin soporte de transparencia. |
| SVG | Iconos, diagramas, logos | Formato vectorial que escala a cualquier tamaño sin pérdida de calidad. Tamaño de archivo diminuto. |
| GIF | Animaciones simples | Puede crecer rápido en tamaño. Considera bucles cortos en .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, así que no hace falta usar PNG.
Buenas 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 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 páginas, especialmente en conexiones móviles. Tamaños objetivo:
- Capturas de pantalla/interfaz: 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 subirlas.
O deja que Jamdesk lo gestione durante el 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 alternan entre distintos 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, así que dimensiones de origen consistentes producen resultados renderizados consistentes.
Jamdesk genera automáticamente una tarjeta social de marca de 1200×630 para cada página, y puedes anularla por página con og:image en el frontmatter. Después de un build, pasa la URL de la página por la herramienta gratuita OpenGraph Preview para ver cómo se renderiza la tarjeta en X, Facebook, LinkedIn, Slack, Discord y más. Consulta Optimización SEO para la configuración completa.
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.jsonHaz referencia a ellas con la ruta completa desde la raíz de tu proyecto:
Evita espacios en los nombres de archivo de imágenes. Usa guiones en su lugar: api-response.webp, no api response.webp.