Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sorgm/data-architecture-docs/llms.txt

Use this file to discover all available pages before exploring further.

Visual content makes documentation more engaging and easier to understand. This guide shows you how to add images, videos, and other media to your Mintlify docs.

​
Adding images

​
Using Markdown syntax

The simplest way to add images is with standard Markdown: 
![Alt text describing the image](/images/example.png)
Always include descriptive alt text for accessibility. Alt text helps screen readers and appears when images fail to load.

​
Image paths

Organize images in the /images directory for easy management: 
![Dashboard screenshot](/images/dashboard.png)
![User profile](/images/screenshots/profile.png)
Your image structure might look like: 
docs/
├── images/
│   ├── logo.png
│   ├── screenshots/
│   │   ├── dashboard.png
│   │   └── profile.png
│   └── diagrams/
│       └── architecture.png

​
Using HTML for more control

Use HTML <img> tags when you need more control over image display: 
<img 
  src="/images/example.png" 
  alt="Example screenshot"
  width="600"
  style={{ borderRadius: '0.5rem' }}
/>

​
The Frame component

Mintlify’s <Frame> component enhances images with borders, shadows, and captions:
Big Bend National Park landscape
<Frame>
  <img 
    src="/images/screenshot.png"
    alt="Application dashboard"
  />
</Frame>

​
Frame with caption

Add captions to provide context:
Analytics dashboard
<Frame caption="The main dashboard showing real-time analytics">
  <img src="/images/dashboard.png" alt="Analytics dashboard" />
</Frame>

​
Image cards

Combine images with cards for organized visual navigation:

Light Mode

Light mode interface

Dark Mode

Dark mode interface
<CardGroup cols={2}>
  <Card title="Light Mode">
    <Frame>
      <img src="/images/light-mode.png" alt="Light mode" />
    </Frame>
  </Card>
  <Card title="Dark Mode">
    <Frame>
      <img src="/images/dark-mode.png" alt="Dark mode" />
    </Frame>
  </Card>
</CardGroup>

​
Hosting images

​
Local images (< 5MB)

Store images under 5MB in your /images directory. They’re automatically optimized and served with your documentation.

​
External hosting (> 5MB)

For larger images or videos, use external hosting:
Cloudinary offers free image hosting with automatic optimization and transformations.
![Screenshot](https://res.cloudinary.com/your-account/image/upload/screenshot.png)

​
Embedding videos

​
YouTube videos

Embed YouTube videos using iframes: 
<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
  style={{ width: '100%', borderRadius: '0.5rem' }}
></iframe>

​
Loom videos

Embed Loom recordings for walkthroughs: 
<iframe
  src="https://www.loom.com/embed/VIDEO_ID"
  frameBorder="0"
  allowFullScreen
  style={{ width: '100%', height: '400px', borderRadius: '0.5rem' }}
></iframe>

​
Self-hosted videos

For self-hosted videos, use the HTML5 <video> tag: 
<video 
  controls 
  width="100%" 
  style={{ borderRadius: '0.5rem' }}
>
  <source src="/videos/demo.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

​
Image optimization tips

1

Compress images

Use tools like TinyPNG or ImageOptim to reduce file sizes without losing quality.
2

Choose the right format

  • PNG: Screenshots, diagrams, images with transparency
  • JPG: Photos, images with many colors
  • SVG: Logos, icons, simple graphics
  • WebP: Modern format with better compression (when supported)
3

Use appropriate dimensions

Resize images to the size they’ll be displayed. Don’t upload a 4K image if it only displays at 800px wide.
4

Add loading optimization

For pages with many images, consider lazy loading:
<img src="/images/large.png" loading="lazy" alt="Description" />

​
Diagrams and illustrations

​
Mermaid diagrams

Create diagrams with code using Mermaid (if supported):

​
Architecture diagrams

For architecture diagrams, consider tools like:

Excalidraw

Hand-drawn style diagrams

Lucidchart

Professional diagramming tool

draw.io

Free diagram editor

Figma

Design and prototyping tool

​
Best practices

Name files descriptively: user-dashboard-overview.png instead of img1.png. This helps with organization and SEO.
Keep image styles consistent throughout your docs. Use the same border radius, shadows, and dimensions for similar content types.
Outdated screenshots confuse users. Review and update images when your product UI changes.
If your docs support dark mode, ensure images look good in both themes. Consider using separate images or transparent backgrounds.
Add arrows, labels, or highlights to screenshots to draw attention to important elements.
Large images slow down page load times. Always optimize images before adding them to your documentation.

​
HTML elements in MDX

Mintlify supports HTML tags in Markdown, giving you infinite flexibility in how you present visual content.
You can use any HTML element: 
<div style={{ display: 'flex', gap: '1rem' }}>
  <img src="/images/before.png" alt="Before" width="50%" />
  <img src="/images/after.png" alt="After" width="50%" />
</div>
This flexibility allows you to create custom layouts and presentations that match your documentation needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us