Skip to main content
The media library in Halo allows you to upload, organize, and manage files like images, videos, documents, and other media for use in your posts, pages, and site design.

​
Understanding attachments

Attachments in Halo:
  • Include images, videos, audio files, documents, and other file types
  • Are stored according to your configured storage policy (local or cloud storage)
  • Can be organized using groups and tags
  • Have metadata like size, media type, and upload date
  • Can be linked to posts, pages, or used standalone
Attachments are independent resources in Halo. Deleting a post or page doesn’t automatically delete its attachments. This prevents accidental data loss when content is removed.

​
Accessing the media library

To access your media library:
1

Navigate to attachments

From the admin dashboard, click on Attachments or Media in the sidebar.
2

View your files

The media library displays all uploaded files in a grid or list view, showing thumbnails, names, and metadata.
3

Filter and search

Use the filter options to view:
  • All attachments
  • Images only
  • Videos only
  • Documents only
  • Attachments by group
  • Attachments by tag

​
Uploading files

​
Uploading to the media library

1

Open the media library

Navigate to Attachments in the admin dashboard.
2

Start upload

Click the Upload button or drag and drop files directly into the media library window.
3

Select files

Choose one or more files from your computer to upload. You can select multiple files at once.
4

Configure upload settings

Before uploading, you can optionally:
  • Select a group to organize the files
  • Add tags for easy retrieval
  • Choose a storage policy (if you have multiple configured)
5

Upload files

Click Upload or Confirm to begin uploading. A progress indicator shows the upload status.
6

Verify upload

Once complete, the files appear in your media library and are ready to use.
Upload limits (file size and count) are determined by your server configuration and storage policy. Contact your system administrator if you need to upload larger files.

​
Uploading within the editor

You can also upload files while editing posts or pages:
1

Position cursor

In the post or page editor, click where you want to insert the media.
2

Insert media

Click the Insert Media or Add Image button in the editor toolbar.
3

Upload or select

Choose to:
  • Upload a new file from your computer
  • Select an existing file from the media library
4

Configure settings

Set options like alignment, size, alt text, and caption.
5

Insert into content

Click Insert to add the media to your content.

​
Organizing attachments

​
Using groups

Groups help you organize attachments into categories:
1

Create a group

In the media library, click New Group or Manage Groups.
2

Name the group

Enter a name for the group (e.g., “Blog Images”, “Product Photos”, “Documents”).
3

Assign attachments

Select attachments and assign them to the group, or set the group when uploading new files.

​
Using tags

Tags provide flexible labeling for attachments:
1

Edit attachment

Click on an attachment to open its details.
2

Add tags

In the Tags field, type tag names separated by commas or press Enter after each tag.
3

Save changes

Click Update to apply the tags.
Use consistent naming conventions for groups and tags to keep your media library organized. Consider creating a tagging strategy before uploading large numbers of files.

​
Managing attachment details

You can view and edit metadata for each attachment:
1

Select attachment

In the media library, click on an attachment to view its details.
2

View information

The detail panel shows:
  • Display Name: Friendly name for the file
  • File Type: MIME type (e.g., image/jpeg, application/pdf)
  • File Size: Size in bytes, KB, or MB
  • Dimensions: For images and videos
  • Upload Date: When the file was uploaded
  • Uploader: User who uploaded the file
  • URL: Direct link to the file
  • Groups and Tags: Organization metadata
3

Edit details

Click Edit to modify:
  • Display name
  • Group assignment
  • Tags
4

Save changes

Click Update to save your modifications.

​
Using attachments in content

​
Inserting images

To add images to posts or pages:
1

Open editor

Edit a post or page where you want to add the image.
2

Insert image

Click the Insert Image button in the editor toolbar.
3

Select image

Choose an image from the media library or upload a new one.
4

Configure display

Set options like:
  • Alt text (for accessibility)
  • Caption
  • Alignment (left, center, right)
  • Size (thumbnail, medium, large, full)
5

Insert

Click Insert to add the image to your content.

​
Linking to files

To create download links for documents or other files:
1

Select text or element

In the editor, select the text or element you want to link.
2

Add link

Click the Link button in the editor toolbar.
3

Choose file

Select Attachment as the link type and choose the file from your media library.
4

Save link

Click OK or Insert to create the link.

​
Setting cover images

To set a featured or cover image for posts and pages:
1

Open settings

In the post or page editor, navigate to the Settings tab.
2

Set cover image

Find the Cover Image section and click Select Image.
3

Choose image

Select an image from the media library or upload a new one.
4

Save

Click Save or Update to set the cover image.

​
Image thumbnails

Halo automatically generates thumbnails for images:
  • Thumbnails are created in different sizes for various uses (list views, card layouts, etc.)
  • Thumbnail generation is handled by your configured storage policy
  • You can view available thumbnails in the attachment details
Thumbnail sizes and generation settings are configured in your storage policy settings. Contact your administrator if you need custom thumbnail sizes.

​
Storage policies

Attachments are stored according to configured storage policies:

​
Local storage

  • Files are stored on your server’s filesystem
  • Suitable for small to medium sites
  • Easier to manage and backup

​
Cloud storage

  • Files are stored in cloud services (S3, OSS, etc.)
  • Suitable for large sites with many media files
  • Offers better scalability and CDN integration
To configure storage policies:
1

Navigate to settings

Go to Settings > Attachments or Storage in the admin dashboard.
2

Configure policies

Set up storage policies with details like:
  • Storage type (local, S3, etc.)
  • Authentication credentials
  • Upload paths
  • Access permissions
3

Set default policy

Choose which storage policy should be used by default for new uploads.
4

Save settings

Click Save to apply your storage configuration.
Changing storage policies doesn’t migrate existing files. Files remain in their original storage location unless you manually migrate them.

​
Deleting attachments

To remove files from the media library:
1

Select attachments

In the media library, select one or more attachments you want to delete.
2

Delete files

Click the Delete button or trash icon.
3

Confirm deletion

Confirm the action when prompted. The files will be permanently removed from storage.
Deleting attachments is permanent and cannot be undone. If the attachment is used in posts, pages, or site design, broken links or missing images will appear. Review usage before deleting important files.

​
Finding where attachments are used

Before deleting an attachment, check where it’s used:
1

Open attachment details

Click on the attachment in the media library.
2

View usage

Look for a Used In or References section that lists:
  • Posts using this attachment
  • Pages using this attachment
  • Theme locations (if used in site design)
3

Review before deleting

If the attachment is in use, consider the impact before deleting it.

​
Best practices for media management

  • Optimize before uploading: Compress images and videos before uploading to save space and improve performance
  • Use descriptive names: Name files clearly so they’re easy to find later
  • Add alt text: Always add alt text to images for accessibility and SEO
  • Organize consistently: Develop a system for groups and tags and use it consistently
  • Clean up regularly: Periodically review and remove unused attachments
  • Use appropriate formats:
    • JPEG for photos
    • PNG for graphics with transparency
    • WebP for modern browsers (better compression)
    • SVG for icons and logos
  • Set reasonable dimensions: Don’t upload images larger than you’ll actually use
  • Back up media files: Regularly backup your media library separately from your database
  • Monitor storage usage: Keep track of how much storage you’re using to avoid running out of space

Build docs developers (and LLMs) love

Get started for freeTalk to us