Skip to content

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.

Basic Images

Inline Images

The simplest way to include an image:

![Alt text for accessibility](/path/to/image.png)

Images with Titles

Add a title that appears on hover:

![Project logo](/favicons/tmuxp.svg "tmuxp project logo")

Image Sizing and Alignment

Default Sizing

Images are constrained to the content width by default and maintain their aspect ratio:

Example badge

HTML for Advanced Control

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;"
/>

Image Galleries

Side-by-Side Images

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>

Grid Layout

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>

Figures with Captions

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>

Responsive Images

Picture Element

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>

Aspect Ratio Control

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

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:

![Vector logo](/favicons/vcspull.svg)

Image Optimization Tips

File Formats

  1. SVG - Best for logos, icons, simple graphics
  2. PNG - Good for images with transparency
  3. JPEG - Best for photographs
  4. WebP - Modern format with better compression

Performance Considerations

  1. Lazy Loading: Images load as they enter viewport
  2. Proper Sizing: Don’t serve larger images than needed
  3. Alt Text: Always provide for accessibility
  4. Compression: Optimize file sizes

Accessibility Best Practices

Alt Text Guidelines

Good alt text examples:

![Screenshot of tmuxp session manager showing multiple terminal panes](/screenshots/tmuxp-demo.png)
![Company logo](/logo.svg)
![Graph showing performance improvements from 2020 to 2024](/charts/performance.png)

Decorative Images

For purely decorative images:

<img src="/decorative-border.png" alt="" role="presentation" />

Common Patterns

Logo Display

<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>

Before/After Comparison

<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>

Image with Text Overlay

<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>

Dark Mode Considerations

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>

Image Error Handling

Provide fallbacks for missing images:

<img
src="/path/to/image.png"
alt="Description"
onerror="this.onerror=null; this.src='/placeholder.png';"
/>

Summary

The image system provides flexibility while maintaining performance and accessibility. Key points:

  1. Always use descriptive alt text
  2. Choose appropriate file formats
  3. Consider responsive display needs
  4. Optimize for performance
  5. Test in both light and dark modes