Documentation

Media Management

SleekCMS provides a centralized media system for managing images, videos, and documents across your site. Instead of scattering media files across individual content records, all media lives in one place — accessible to every model, every page, and every team member.

This page covers how media management works in SleekCMS, what media types are supported, and how centralized media improves collaboration and maintainability. Implementation details for image optimization, video embedding, and file handling are covered in the linked sub-pages.

Why Centralized Media

In a traditional CMS workflow, media files are often uploaded inline — attached to a specific blog post, embedded in a particular page, managed by whoever happens to be editing that content. This creates problems as your site grows. The same logo gets uploaded four times. A product photo lives in one post but can't be found when another team member needs it. Updating a headshot means hunting through every page that uses it.

SleekCMS takes a different approach. All media — images, videos, and documents — is managed in a shared media library at the site level. Content records reference media from this library rather than owning their own copies. This has several practical benefits.

Team collaboration. Any team member with media access can upload, organize, and manage assets independently of content editing. A designer can prepare images while a writer drafts copy. A marketing manager can update brand assets without touching page content. Media management and content editing are parallel workflows, not sequential ones.

Update once, update everywhere. When a media asset is referenced from the library rather than duplicated per record, replacing that asset updates it everywhere it's used. Swap out a product photo in the media library and every page, entry, and block that references it reflects the change immediately — no need to edit individual content records or update code.

Consistency across the site. A shared library prevents duplicate uploads and naming inconsistencies. Your team works from a single source of truth for visual assets, which keeps the site's media organized and reduces storage waste.

Media Types

SleekCMS supports three categories of media, each with different capabilities and workflows.

Images

Images are the most fully featured media type in SleekCMS. The platform handles the entire image lifecycle — upload, storage, transformation, optimization, and delivery — with no external services or build configuration required.

When you upload an image, SleekCMS stores the original file and makes it available through a CDN-backed URL. From there, you can transform and optimize images on the fly using URL parameters — resize, crop, change format, adjust quality, apply filters — without touching the original file or writing any code.

Image fields in your content models reference images from the media library. Editors select images through a picker that supports multiple sources: the site's media gallery for previously uploaded images, local file upload, and integrated third-party sources including Unsplash, Pexels, Pixabay, and Iconify. Editors can also provide a direct URL for externally hosted images.

In templates, the site builder provides helper functions — src(), img(), picture(), and svg() — that generate optimized image URLs and HTML elements with the correct attributes. These helpers handle responsive images, dark/light theme variants, format conversion, and fallback behavior automatically.

→ Image Management & Optimization

Videos

Video fields store references to externally hosted video content — typically YouTube, Vimeo, or other video platform URLs. SleekCMS does not currently host video files directly. You add a video field to your content model, and editors provide the URL to a hosted video. Your templates or frontend code handles the embed rendering.

This approach keeps your CMS lightweight and leverages the streaming infrastructure of dedicated video platforms. Native video hosting is planned for a future release.

Documents

Document assets — PDFs, spreadsheets, presentations, and other files — can be uploaded and managed through the media library. These are available for download linking in your content or for direct reference from content fields.

Documents are stored and served as-is, without the transformation capabilities available for images. They're useful for downloadable resources like whitepapers, menus, brochures, spec sheets, and any file your site visitors need to access.

→ File and Document Assets

Image Transformation and Optimization

One of the most powerful aspects of SleekCMS's media system is native image transformation. Every image in your media library can be resized, cropped, converted, and optimized on the fly through URL parameters — no image editing software, no build-time processing, no third-party services to configure.

The transformation service supports a comprehensive set of operations:

Resizing and cropping — Set width, height, and fit mode (cover, contain, fill, inside, outside). Specify crop position and gravity for precise control over what part of the image is shown. Support for device pixel ratio means retina-ready images with a single parameter.

Format conversion — Convert between WebP, AVIF, PNG, JPEG, GIF, and TIFF on the fly. Serve modern formats like WebP and AVIF to browsers that support them, with automatic quality control.

Visual adjustments — Apply blur, sharpening, rotation, flipping, rounded corners, grayscale, color tinting, and brightness/contrast/saturation adjustments. These are applied at the CDN edge, not stored as separate files.

Padding and borders — Extend image edges with configurable padding and background colors, useful for creating consistent aspect ratios or adding visual breathing room.

All transformations are applied via URL query parameters on the image's CDN URL. The original file is never modified. This means the same source image can be served at different sizes, formats, and crop ratios across your site — a hero banner version, a thumbnail version, and an Open Graph social preview version — all from a single upload.

In the site builder, the src() helper generates these transformation URLs from simple parameters:

<!-- Resize to 800×600 -->
<img src="<%- src(item.hero, '800x600') %>" alt="<%- item.hero.alt %>">

<!-- Object form with format and fit -->
<img src="<%- src(item.thumbnail, { w: 400, h: 300, fit: 'cover', type: 'webp' }) %>">

Through the content API, image objects include the raw URL that you can append parameters to in your own frontend:

const page = client.getPage('/blog/hello-world');
// page.image.raw → 'https://img.sleekcms.com/az41/m7urgy6z'
// Append params: page.image.raw + '?w=800&h=600&fmt=webp'

// Or use the ready-made URL with default format:
// page.image.url → 'https://img.sleekcms.com/az41/m7urgy6z.webp'

→ Image Management & Optimization → Image Processing Configuration

Media in Content Models

Media integrates into your content models through dedicated field types. Each field type is designed for a specific media category and provides the appropriate editor experience.

Image fields support single or multiple image selection. A single image field is used for hero images, author headshots, or logos. A multiple image field is used for photo galleries, product image carousels, or any content that needs more than one image. Editors pick from the media gallery, upload new files, or pull from integrated sources — all within the content editor.

Video fields store a single external video URL. Editors paste in a YouTube, Vimeo, or other platform link. The URL is stored as a string in the content record.

Reference fields can link to document entries if you model your documents as an entry collection. This gives you structured metadata alongside the file — a title, description, category, and the file itself.

In API responses, image fields return an object with the image URL, alt text, raw URL for transformations, source information, and theme variant URLs for dark/light mode support. Video fields return the URL string. This gives your frontend everything it needs to render media correctly.

→ Content Field Types

Media in Templates

The site builder provides a set of helper functions specifically for working with media in your EJS templates. These helpers handle the common patterns — generating optimized URLs, building responsive HTML elements, supporting theme variants — so your templates stay clean.

src(obj, attr) generates an optimized image URL with resizing parameters. Pass an image object and dimensions, get back a CDN URL with the right query parameters.

img(obj, attr) generates a complete <img> HTML element with the optimized source URL, alt text, and optional CSS class and style attributes.

picture(obj, attr) generates a <picture> element with automatic dark/light theme variant support using prefers-color-scheme media queries. When an image has theme variants configured, the picture() helper includes the appropriate <source> elements.

svg(obj, attr?) inlines an SVG file with custom attributes applied directly to the SVG element. This is useful for logos, icons, and other vector graphics where you need to control size, color, or CSS class via attributes.

All image helpers include fallback behavior — when an image object is missing or invalid, they generate a placeholder image URL so layouts don't break during development.

→ Template Context and Data Access → Model Templates

Media and the Content API

When consuming media through the content API rather than the site builder, media data is included inline in the content records that reference it.

An image field returns an object with this structure:

const page = client.getPage('/blog/hello-world');
// page.image → {
//   url: 'https://img.sleekcms.com/az41/m7urgy6z.webp',   // CDN URL with default format
//   raw: 'https://img.sleekcms.com/az41/m7urgy6z',         // Base URL for custom transformations
//   alt: 'Description of the image',                        // Alt text set by editors
//   source: 'unsplash',                                     // Source platform (if applicable)
//   light: null,                                            // Light theme variant URL
//   dark: null                                              // Dark theme variant URL
// }

Named images — images uploaded to the media library with a specific key rather than attached to a content field — can be retrieved directly:

const logo = client.getImage('site-logo');
// { url: '...', raw: '...', alt: 'Company logo' }

Your frontend uses the raw URL to build custom transformation URLs by appending query parameters, or uses the url directly for the default format.

→ Content API → @sleekcms/client

What's Next