Images & Media
On this page
This page demonstrates how images and media are handled in the markdown system, including responsive images, captions, and various display options.
The simplest way to include an image:
Add a title that appears on hover:
Images are constrained to the content width by default and maintain their aspect ratio:
When you need more control over image display:
<img src="/favicons/g.svg" alt="G logo" width="100" height="100" /><img src="/favicons/cihai.svg" alt="Cihai logo" style="max-width: 200px;"/>Using HTML for layout control:
<div style="display: flex; gap: 1rem; justify-content: center;"> <img src="/favicons/tmuxp.svg" alt="tmuxp" width="80" /> <img src="/favicons/libtmux.svg" alt="libtmux" width="80" /> <img src="/favicons/vcspull.svg" alt="vcspull" width="80" /></div>For multiple images:
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(100px, 1fr)); gap: 1rem;"> <img src="/favicons/django-docutils.svg" alt="Django Docutils" /> <img src="/favicons/django-slugify-processor.svg" alt="Django Slugify" /> <img src="/favicons/gp-libs.svg" alt="GP Libs" /> <img src="/favicons/social-embed.ico" alt="Social Embed" /></div>Using HTML figure elements:
<figure> <img src="/favicons/cihai.svg" alt="Cihai project logo" /> <figcaption>The Cihai project logo represents Chinese character data processing</figcaption></figure>For different images at different screen sizes:
<picture> <source media="(max-width: 600px)" srcset="/path/to/mobile-image.png"> <source media="(min-width: 601px)" srcset="/path/to/desktop-image.png"> <img src="/path/to/fallback-image.png" alt="Responsive image example"></picture>Maintaining aspect ratios:
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"> <img src="/favicons/tmuxp.svg" alt="16:9 aspect ratio" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; object-fit: contain;" /></div>SVG images are perfect for logos and icons:
- Scalable: Look crisp at any size
- Small file size: Efficient for web delivery
- Styleable: Can be colored with CSS
- Accessible: Support for titles and descriptions
Example SVG handling:
- SVG - Best for logos, icons, simple graphics
- PNG - Good for images with transparency
- JPEG - Best for photographs
- WebP - Modern format with better compression
- Lazy Loading: Images load as they enter viewport
- Proper Sizing: Don’t serve larger images than needed
- Alt Text: Always provide for accessibility
- Compression: Optimize file sizes
Good alt text examples:


For purely decorative images:
<img src="/decorative-border.png" alt="" role="presentation" /><div style="display: flex; align-items: center; gap: 1rem;"> <img src="/favicons/tmuxp.svg" alt="tmuxp logo" width="40" height="40" /> <span>tmuxp - Session Manager for tmux</span></div><div style="display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;"> <figure> <img src="/before.png" alt="Before optimization" /> <figcaption>Before</figcaption> </figure> <figure> <img src="/after.png" alt="After optimization" /> <figcaption>After</figcaption> </figure></div><div style="position: relative; display: inline-block;"> <img src="/hero-bg.jpg" alt="Hero background" /> <div style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); color: white; text-align: center;"> <h2>Overlay Text</h2> <p>Description here</p> </div></div>Some images may need different versions for dark mode:
<picture> <source media="(prefers-color-scheme: dark)" srcset="/logo-dark.svg" > <img src="/logo-light.svg" alt="Company logo" /></picture>Provide fallbacks for missing images:
<img src="/path/to/image.png" alt="Description" onerror="this.onerror=null; this.src='/placeholder.png';"/>The image system provides flexibility while maintaining performance and accessibility. Key points:
- Always use descriptive alt text
- Choose appropriate file formats
- Consider responsive display needs
- Optimize for performance
- Test in both light and dark modes