MeetBall Handbook

Images & Media

Making your content visual with images, videos, and other media assets.

Where to Put Images

All images go in the static/ directory:

static/
├── images/           # General images
│   ├── screenshots/  # UI screenshots  
│   ├── diagrams/     # Architecture diagrams
│   └── icons/        # Small icons and graphics
├── videos/           # Video files (if needed)
└── docs/            # Documentation-specific assets
    └── guide-name/   # Images for specific guides

Adding Images

Basic Image

![Alt text](/images/screenshot.png)

Image with Caption

![MeetBall architecture diagram](/images/diagrams/architecture.png)
*How our system connects everything together*

Responsive Image

For images that should scale on mobile:

<img src="/images/screenshot.png" alt="Dashboard view" style="max-width: 100%; height: auto;">

Image Optimization

Before Adding Images:

  1. Resize appropriately: 1200px wide max for screenshots
  2. Compress: Use tools like TinyPNG or ImageOptim
  3. Choose right format:
    • .png for screenshots with text
    • .jpg for photos
    • .svg for icons and simple graphics
    • .webp for best compression (if browser support is OK)

Naming Convention

Use descriptive names:

✅ dashboard-main-view.png
✅ login-process-diagram.svg
❌ screenshot1.png  
❌ image.jpg

Screenshots

Taking Good Screenshots

  • Clean desktop: Hide personal stuff from screenshots
  • Consistent browser: Use same browser for all UI screenshots
  • Highlight important parts: Use arrows or boxes to show what matters
  • High DPI: Take screenshots on retina/high-DPI screens when possible

Annotating Screenshots

Use tools like:

  • macOS: Built-in screenshot markup
  • CleanShot X: Great for annotations
  • Figma: For creating diagrams and mockups

Videos

Embedding YouTube


<div class="youtube-wrapper" data-youtube-id="dQw4w9WgXcQ">
  <div class="youtube-placeholder" onclick="loadYouTubeVideo(this, 'dQw4w9WgXcQ')">
    <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" 
         alt="YouTube video thumbnail" 
         loading="lazy"
         onerror="this.src='https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg'">
    <button class="youtube-play-button" aria-label="Play video">
      <svg viewBox="0 0 68 48" style="width: 68px; height: 48px;">
        <path d="M66.52,7.74c-0.78-2.93-2.49-5.41-5.42-6.19C55.79,.13,34,0,34,0S12.21,.13,6.9,1.55 C3.97,2.33,2.27,4.81,1.48,7.74C0.06,13.05,0,24,0,24s0.06,10.95,1.48,16.26c0.78,2.93,2.49,5.41,5.42,6.19 C12.21,47.87,34,48,34,48s21.79-0.13,27.1-1.55c2.93-0.78,4.64-3.26,5.42-6.19C67.94,34.95,68,24,68,24S67.94,13.05,66.52,7.74z" fill="#f00"></path>
        <path d="M 45,24 27,14 27,34" fill="#fff"></path>
      </svg>
    </button>
  </div>
</div>

<style>
  .youtube-wrapper {
    position: relative;
    padding-bottom: 56.25%; /* 16:9 aspect ratio */
    height: 0;
    overflow: hidden;
    max-width: 100%;
    min-width: 400px;
    margin: 0;
    border-radius: 12px;
    background: #000;
    isolation: isolate;
  }
  
  .youtube-placeholder {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    cursor: pointer;
    display: flex;
    align-items: center;
    justify-content: center;
  }
  
  .youtube-placeholder img {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
    border-radius: 12px;
  }
  
  .youtube-play-button {
    position: relative;
    z-index: 1;
    background: transparent;
    border: none;
    cursor: pointer;
    transition: transform 0.2s ease;
  }
  
  .youtube-play-button:hover {
    transform: scale(1.1);
  }
  
  .youtube-wrapper iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    border: 0;
    border-radius: 12px;
    clip-path: inset(0 round 12px);
  }
</style>

<script>
function loadYouTubeVideo(element, videoId) {
  const wrapper = element.parentElement;
  const iframe = document.createElement('iframe');
  iframe.src = `https://www.youtube-nocookie.com/embed/${videoId}?rel=0&autoplay=1`;
  iframe.title = 'YouTube video player';
  iframe.frameBorder = '0';
  iframe.allow = 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share';
  iframe.allowFullscreen = true;
  
  // Replace placeholder with iframe
  wrapper.innerHTML = '';
  wrapper.appendChild(iframe);
}
</script>

This creates a responsive embed that works on all screen sizes.

Local Video Files

Put in static/videos/ and embed:

<video controls style="max-width: 100%;">
  <source src="/videos/demo.mp4" type="video/mp4">
  Your browser doesn't support video.
</video>

Icons & Graphics

Using Existing Icons

Check what's already in static/images/icons/ before adding new ones.

Creating Consistent Graphics

  • Colors: Use MeetBall brand colors
  • Style: Keep consistent with existing graphics
  • Size: Standard icon sizes (16px, 24px, 32px, 64px)

Diagrams

Mermaid (Preferred)

Use Mermaid for flow charts and diagrams:

```mermaid
graph TD
    A[User submits] --> B[Process request]
    B --> C{Valid?}
    C -->|Yes| D[Save to database]
    C -->|No| E[Show error]
```

Image Diagrams

For complex diagrams, create in:

  • Figma: For UI mockups and flows
  • Draw.io: For technical diagrams
  • Excalidraw: For sketchy, informal diagrams

Save as .svg when possible for crisp scaling.

File Size Guidelines

  • Screenshots: Under 500KB each
  • Diagrams: Under 200KB
  • Icons: Under 50KB
  • Videos: Under 10MB (prefer YouTube embeds)

Accessibility

Always include alt text:

![Screenshot showing the main dashboard with navigation menu on left and charts on right](/images/dashboard.png)

Make it descriptive for screen readers!

Testing Images

Before committing:

  1. Test locally: Run zola serve and check images load
  2. Check mobile: Resize browser window to see how images scale
  3. Verify paths: Make sure image paths are correct (start with /)

Common Issues

Image Not Showing?

  • Check the path starts with / (like /images/pic.png)
  • Make sure image is in static/ directory
  • Check file name spelling and case sensitivity

Image Too Big on Mobile?

Add CSS:

<img src="/images/big-screenshot.png" alt="Description" style="max-width: 100%; height: auto;">

Remember: Good visuals make docs way more helpful! 📸

← Code of Conduct
FAQ →