md0 CMS provides tools for uploading and managing media files directly in your GitHub repository. This guide covers media upload, organization, and optimization.
How Media Works
Git-Based Storage
Media files in md0 CMS are stored directly in your GitHub repository:
- Files are committed to your repository
- Version controlled like code
- Accessible to your static site generator
- No separate media hosting required
Media Workflow
- Upload file through md0 CMS
- File is committed to specified folder
- URL is generated and inserted
- Your SSG can reference the file
Uploading Media
Upload Methods
Drag and Drop:
- Drag file from your computer
- Drop into editor or media library
- File uploads automatically
File Browser:
- Click Upload button
- Select file from computer
- Confirm upload
Paste from Clipboard:
- Copy image (screenshot, etc.)
- Paste into editor with
Cmd/Ctrl + V - Image uploads automatically
Upload Locations
Configure upload destinations in settings:
# Example configuration
Media Folder: /public/images
Subfolder Pattern: /posts/{year}/{month}
Common patterns:
/public/images → All images in one folder
/static/media → For Gatsby/Hugo
/public/uploads → General uploads
/images/{year} → Organized by year
/media/{collection} → Per collection
Media Library
Accessing Media Library
- Click Media icon in sidebar
- Browse uploaded files
- Filter and search
- Select file to insert
Library Features
View modes:
- Grid view (thumbnails)
- List view (details)
Filtering:
- By file type (images, documents, videos)
- By upload date
- By collection/folder
- By size
Sorting:
- By name (A-Z, Z-A)
- By date (newest, oldest)
- By size (largest, smallest)
- By type
File Details
Click a file to see:
- File name
- File size
- Dimensions (for images)
- Upload date
- File path
- Public URL
Image Management
Supported Formats
Recommended formats:
- JPEG/JPG (photos, complex images)
- PNG (graphics, transparency)
- WebP (modern, optimized)
- SVG (icons, logos)
Also supported:
- GIF (animations)
- AVIF (next-gen format)
Image Optimization
Before uploading:
- Resize to appropriate dimensions
- Compress to reduce file size
- Use correct format for content type
- Consider using WebP or AVIF
Recommended tools:
- TinyPNG (online compression)
- ImageOptim (Mac)
- Squoosh (web-based)
- Sharp (Node.js)
Image Size Guidelines
Blog post images:
- Featured: 1200x630px (social sharing)
- Content: 800-1200px wide
- Thumbnails: 400x300px
- File size: < 200KB
Documentation:
- Screenshots: Actual size or scaled down
- Diagrams: 800-1000px wide
- Icons: 24px, 32px, 48px (SVG preferred)
- File size: < 100KB
Performance:
- Hero images: 1920px wide max
- Regular images: 1200px wide max
- Thumbnails: 400px wide max
- File size: Keep under 200KB per image
Organizing Media
Folder Structure
Organize media to match your content:
public/
└── images/
├── blog/
│ ├── 2024/
│ │ ├── post-1-hero.jpg
│ │ └── post-2-hero.jpg
│ └── authors/
│ └── jane-doe.jpg
├── docs/
│ ├── screenshots/
│ └── diagrams/
└── shared/
├── logos/
└── icons/
Naming Conventions
Good naming:
post-title-hero-image.jpg
screenshot-dashboard-overview.png
diagram-architecture.svg
author-jane-doe.jpg
Bad naming:
IMG_1234.jpg
Screen Shot 2024-01-15.png
untitled.png
image (1).jpg
Best practices:
- Use lowercase
- Use hyphens, not spaces
- Be descriptive
- Include context
- Avoid generic names
Using Media in Content
Insert in Editor
Via toolbar:
- Click Image button
- Upload or select from library
- Add alt text
- Insert
Via drag and drop:
- Drag image from desktop
- Drop into editor
- Add alt text in properties
Via markdown:
Image Frontmatter
Use images in frontmatter fields:
---
title: "My Post"
featured_image: /images/hero.jpg
author_avatar: /images/authors/jane.jpg
gallery:
- /images/photo1.jpg
- /images/photo2.jpg
- /images/photo3.jpg
---
Relative vs Absolute Paths
Absolute paths (recommended):
Works from any page depth.
Relative paths:
Depends on file location.
Advanced Media Features
Image Captions
_Dashboard showing the main interface_
Linked Images
[](/images/full.jpg)
Image Dimensions
Specify size in HTML:
<img src="/images/logo.png" width="200" height="100" alt="Logo" />
Or let CSS handle it:
Multiple Images
Image gallery:
Side-by-side (with HTML):
<div style="display: flex; gap: 1rem;">
<img src="/images/before.jpg" alt="Before" style="width: 50%;" />
<img src="/images/after.jpg" alt="After" style="width: 50%;" />
</div>
Non-Image Media
PDF Files
Upload and link to PDFs:
[Download PDF guide](/files/guide.pdf)
Recommended folder:
/public/files/
/static/downloads/
/public/documents/
Video Files
Direct upload (small files):
<video controls>
<source src="/videos/demo.mp4" type="video/mp4" />
</video>
External hosting (recommended):
[Watch video on YouTube](https://youtube.com/watch?v=...)
Documents
Upload and link:
[Download documentation](/files/docs.pdf)
[View spreadsheet](/files/data.xlsx)
Media Performance
Optimization Checklist
- [ ] Compress images before upload
- [ ] Use appropriate formats (WebP, AVIF)
- [ ] Resize to display dimensions
- [ ] Use SVG for logos and icons
- [ ] Enable lazy loading
- [ ] Add proper alt text
- [ ] Use responsive images
Lazy Loading
Many SSGs support lazy loading:
<img src="/image.jpg" loading="lazy" alt="Description" />
Responsive Images
Use srcset for responsive images:
<img
src="/image-800.jpg"
srcset="/image-400.jpg 400w, /image-800.jpg 800w, /image-1200.jpg 1200w"
sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
alt="Description"
/>
Git Considerations
Large Files
Git limitations:
- Large files slow down cloning
- Git isn't designed for binary files
- Repository size can become unwieldy
Solutions:
- Optimize before uploading (compress, resize)
- Use external hosting for videos
- Archive old media periodically
- Consider Git LFS for large files
Git LFS (Large File Storage)
For repositories with many large files:
# Install Git LFS
git lfs install
# Track image files
git lfs track "*.jpg"
git lfs track "*.png"
# Commit and push
git add .gitattributes
git commit -m "Configure Git LFS"
md0 CMS works with Git LFS-enabled repositories.
File Size Limits
GitHub limits:
- Single file: 100MB (hard limit)
- Repository: 1GB recommended
- With Git LFS: 2GB per file
Recommendations:
- Keep images under 1MB
- Keep total media under 100MB
- Use external hosting for large files
Best Practices
Organization
- Create logical folder structure
- Use consistent naming
- Delete unused media
- Document media locations
- Keep media close to content
Performance
- Compress all images
- Use modern formats (WebP, AVIF)
- Implement lazy loading
- Use appropriate dimensions
- Consider CDN for production
Accessibility
- Always add alt text
- Use descriptive filenames
- Provide captions when needed
- Don't embed text in images
- Test with screen readers
Version Control
- Commit media with related content
- Use meaningful commit messages
- Don't commit unused files
- Archive old media
- Document media changes
Troubleshooting
Upload Failed
Check:
- File size is under limit
- File type is supported
- Folder path is correct
- Repository has write access
Image Not Displaying
Check:
- Path is correct
- File exists in repository
- File extension matches
- No typos in filename
Slow Upload
Solutions:
- Compress file before upload
- Check internet connection
- Upload smaller batch
- Try again later
Next Steps
- Markdown Editing - Use media in content
- GitHub Sync - How media syncs
- Integration Guides - Use media in your site