Asset Library

Sveltia CMS’s Asset Library allows users to efficiently manage and organize media files, including images, videos, and documents. It serves as a centralized hub for all digital assets, making it easy to upload, categorize, and retrieve files as needed — whether they are stored in the Git repository with the internal media storage or on an external media storage provider such as Amazon S3, Cloudflare R2 or Uploadcare.

Features

The Asset Library includes the following features:

Folder List

The sidebar displays a list of all folders in the repository’s global media folder, as well as any collection-specific media folders. If any cloud storage services are configured, they are also listed in the sidebar under External Locations.

Internal Locations

Navigate between the global media folder and collection-specific media folders. This allows organizing assets at both the global level and within individual collections for more granular asset management. Within each of these folders, users can also browse and manage subfolders.

External Locations

Assets in external locations are listed under External Locations in the sidebar. This includes any configured cloud storage services, as well as a special location for linked files.

Cloud Storage Services

Every cloud storage service configured with the media_libraries option is listed under External Locations in the sidebar, at #/assets/-/{service} — for example #/assets/-/uploadcare. Select a service to browse the files stored there, using the same grid or list views, sorting, type filter and Info pane as a repository folder. A search box narrows the list down by file name.

The user is prompted for the service’s secret key or SAS token the first time, just like in the File and Image field picker; the credential is stored in the browser only and can be changed later under Settings > Media. Files can be uploaded, downloaded, renamed, replaced and deleted directly on the service, subject to what its API allows:

Service	Upload	Delete	Rename	Replace
Amazon S3, Backblaze B2, Bunny Storage, Cloudflare R2, DigitalOcean Spaces, Scaleway Object Storage, Supabase Storage	Yes	Yes	Yes	Yes
Azure Blob Storage	Yes	Yes	Yes	Yes
Uploadcare	Yes	Yes	No	No
Cloudinary	Cloudinary’s own Media Library widget is opened instead

The controls for operations a service doesn’t support are hidden. Renaming a file on an S3-compatible service or Azure Blob Storage copies it to the new name and then deletes the original. Make sure the bucket’s CORS policy allows the DELETE method and all request headers, and that the credential has the delete permission — see the setup instructions of each service for details. Unlike repository assets, entries referencing a renamed or deleted external file are not updated, because the file URL is stored as is.

INFO

Files on external services are previewed straight from the service’s URL, so the details view can show a text or Markdown file only if the service allows cross-origin requests. The Info pane shows the file size, the dimensions and duration of media files, the public URL, the file path on the service and the entries using the file, but not the Exif metadata, which can’t be read without downloading the file. The Copy menu offers the public URL, the file path relative to the configured prefix, the service’s file ID (an object key or a UUID) and the file data. These files are not included in the global search.

Linked Files

The last item under External Locations, Linked Files at #/assets/-/linked, gathers every file that a File or Image field links to by URL — a picture hosted on another site, a document on a shared drive, an avatar served by a third-party API — so that all of them can be seen in one place and check where each one is used. The list is built from the entries themselves, so it needs no configuration and stays in sync as entries are saved. A URL used by several entries is listed once.

Files that live in the repository or on a configured cloud storage service have their own locations, so they aren’t listed here, even when an entry stores them as an absolute URL. Images embedded in Markdown or rich text bodies aren’t scanned either.

Since these files are hosted elsewhere, they can only be browsed: there is no upload, rename, replace or delete. The Info pane shows the kind, the dimensions or duration of a media file, the URL and the entries using the file, and the Copy menu offers the URL and, where the host allows cross-origin requests, the file data. The file size isn’t available. A URL without a file extension, such as an avatar endpoint, is treated as an image when it comes from an Image field.

A long list is easier to go through host by host: choose Domain from the Group menu in the toolbar to group the files by the domain of their URL. The choice is remembered for this location.

The CMS also checks whether each file can still be loaded, and marks one that can’t — deleted, moved or on a host that is gone — with an Unavailable badge, so a broken link stands out. A missing non-media file on a host that doesn’t allow cross-origin requests can’t be detected, though.

Subfolders

A repository folder is browsed folder by folder, the way a file manager works. The subfolders of the current folder are listed ahead of its assets — as compact tiles in the grid view, or as rows in the list view — and double-clicking one (or a single click or tap on a touch screen or a small screen) opens it. A breadcrumb in the toolbar shows the current location and leads back to any parent folder, and the browser’s Back button works as well, since each folder has its own URL, such as #/assets/static/images/2024/summer. The All Assets location lists every asset at once instead.

Click the empty area of the list, or select a folder with a single click or the keyboard, to see the folder’s path and what it holds in the Info pane.

Folders can be managed like assets:

• Create a folder with the New Folder button in the toolbar. A Git repository can’t hold an empty folder, so the CMS commits a .gitkeep placeholder file to keep it in the repository until something is uploaded to it. The name is sanitized like a file name, and slugified as well if that option is enabled.
• Upload files into the current folder: both the Upload button and drag and drop save the files there.
• Rename a folder from its options menu. Every asset in the folder, at any depth, is moved along in the same commit, and the File and Image fields and Markdown images that reference them are updated with the new paths.
• Delete a folder and everything in it from its options menu. As with deleting assets, the entries referencing any of the assets are updated in the same commit, the confirmation dialog says how many, and the deletion is refused if clearing a reference would break a field’s validation rules.

Subfolder browsing applies to any global, collection or asset collection folder with a fixed path. A collection media folder whose path contains a template tag such as {{slug}}, or an entry-relative folder, doesn’t have a single tree to walk, so its assets are listed all at once as before. A collection media folder nested inside the global media folder is its own location in the sidebar rather than a subfolder of the global one.

When working with a local repository, a folder that is left empty by a move or deletion is removed from the disk, so the local checkout matches what a Git commit would leave. Open Authoring contributors can browse folders but can’t create, rename or delete them, as those changes are committed straight to the branch.

Read-Only Folders

The files in a folder named admin or cms, at any depth, are listed but read-only, because the CMS itself is usually served from such a folder. With a media folder at the root of the public folder, such as static or public, the CMS’s own admin page and configuration file — static/admin/index.html and static/admin/config.yml, for example — would otherwise appear as assets, and replacing them would hand the next user’s sign-in to whoever wrote the new page.

• The files can’t be replaced, edited, renamed, moved or deleted.
• Nothing can be uploaded to such a folder, and no folder can be created in it.
• The folder itself can’t be renamed or deleted, and a new or renamed folder can’t be called admin or cms.

The same applies to the picker of the File and Image fields, and to the Editorial Workflow: a pull request that changes a file in such a folder as an asset isn’t published from the CMS. Make changes to the admin page in the repository directly. Deployment configuration files such as _redirects aren’t affected, and can still be edited through a file collection; see Editing Site Deployment Configuration Files.

Folders on External Locations

Amazon S3 and the S3-compatible providers, as well as Azure Blob Storage, store files at paths, so they are browsed folder by folder the same way, with the same breadcrumb, Info pane, New Folder button and folder menu. As object storage has no folders of its own, the CMS keeps an empty folder with a zero-byte placeholder object named after the folder with a trailing slash, which is what the consoles of these services do, and it reads the other folders off the file paths. Renaming a folder copies each file to its new path and deletes the original, one file at a time, since the services can’t move a file, and deleting a folder deletes each file in it. Keep in mind that the entries link to the files on these services by URL, so a rename changes those URLs and the entries using them aren’t updated. The search box in the location’s toolbar looks through every folder, listing the matches with their paths.

Uploadcare has no folders, and Cloudinary handles them in its own widget, so neither is affected.

Asset List

Thumbnails are displayed for image, video and PDF files for easy identification. Users can switch between grid and list views, and sort or filter assets by name and file type.

Thumbnails of entries are also displayed in both grid and list views, making it easier to navigate and identify the assets needed.

Asset Upload

Upload multiple assets at once by browsing or dragging and dropping files directly into the library, including files in nested folders. When an entry or asset file is deleted, the empty folder that contains it is also automatically deleted, so there is no need to clean it up manually.

The CMS prevents the same file from being uploaded twice by comparing file hashes and selecting an existing asset instead.

Asset Search

Use the search functionality to quickly find specific assets. Assets can also be filtered by name or file type to narrow down results. Files on external locations are searched with the search box in the location’s own toolbar instead.

Asset Details

Preview image, audio, video, text and PDF files directly in the Asset Library. Check the site’s Content Security Policy (CSP) if the preview doesn’t work as expected.

View comprehensive asset details including:

• File size and dimensions
• Commit author and date information
• A list of entries that use the selected asset
• Exif metadata when available, including creation date and GPS coordinates displayed on a map

Asset Management

Manage assets with a variety of operations:

• Rename existing assets. If the asset is used in any entries, the File and Image fields will be automatically updated with the new file path.
• Replace existing assets with new versions.
• Edit plain text assets, including Markdown, JSON, SVG files and other text-based content using the built-in editor.
• Copy the public URL, file path, text data, or image data of a selected asset to the clipboard.
• Download one or more selected assets at once.
• Delete one or more selected assets at once. If an asset is used in any entries, those entries are updated in the same commit so that no reference is left dangling: a File or Image field holding it is cleared, or loses that item if it holds several files, and an image embedding it in a Markdown or rich text field is removed. The confirmation dialog says how many entries will be updated. The deletion is refused, though, if clearing a reference would break a field’s own validation rules — a required Image field with nothing left, a multi-file field with fewer than min files, or a required body with nothing but the image — and the dialog then lists the entries and fields in the way so that they can be updated first. The Info pane’s Used in list shows what an asset is used by before deleting.

Future Plans

Image editing capabilities, such as cropping and resizing, will be added in future releases. Advanced DAM features, such as tagging and metadata management, are also planned for future updates.