Images & MediaLink to section

This page demonstrates how images and media are handled in the markdown system, including responsive images, captions, and various display options.

Basic ImagesLink to section

Inline ImagesLink to section

The simplest way to include an image:

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

Images with TitlesLink to section

Add a title that appears on hover:

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

Image Sizing and AlignmentLink to section

Default SizingLink to section

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

Example badge

HTML for Advanced ControlLink to section

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 GalleriesLink to section

Side-by-Side ImagesLink to section

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 LayoutLink to section

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 CaptionsLink to section

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 ImagesLink to section

Picture ElementLink to section

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 ControlLink to section

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 ImagesLink to section

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 TipsLink to section

File FormatsLink to section

  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 ConsiderationsLink to section

  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 PracticesLink to section

Alt Text GuidelinesLink to section

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 ImagesLink to section

For purely decorative images:

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

Common PatternsLink to section

Logo DisplayLink to section

<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 ComparisonLink to section

<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 OverlayLink to section

<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 ConsiderationsLink to section

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 HandlingLink to section

Provide fallbacks for missing images:

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

SummaryLink to section

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
Return to the homepage