On this page
Content

Upload images

Upload images to the Media Library and add them to your content. Images are committed to your repository when the content publishes.

GuideFor Owners, Admins, Managers, Developers and EditorsUpdated June 7, 2026

Images live in your project's Media Library until you use them in content. When content publishes, the images it uses are committed to your repository alongside the Markdown. This guide uploads an image and adds it to content.

Who this is for

Owners, Admins, Managers, Developers and Editors, the roles that can upload and manage images.

Before you start

  • You have a project. See Create your first project.
  • Your image is one of the supported formats and within the size limit (below).

Upload an image

  1. Open your project and go to Media.
  2. Choose to upload, then select or drag in your image file.
  3. Optionally choose a context for the image, then confirm with Upload Media.

Supported formats are JPG, PNG, WebP, AVIF, and GIF, up to 10 MB per file. Acrosite optimises images on upload.

Note
Each image can be up to 10 MB on every plan. Your plan limits how many images the workspace can store. See Billing, trial, and plan limits.

Add an image to content

Inside the editor, add an Image block in the body (or use the Featured Image card) to open the image picker, then choose a source:

  • Upload New Image — upload a new file (it is staged in the Media Library), or
  • Choose Project Media — pick a staged image already in the project, or
  • Choose Published Media — pick an image already published to your site, or
  • Image From URL — reference an image hosted elsewhere by its URL.

When you insert an image, you can set its alt text, an optional title, and a caption. For a Post's featured image, use the featured image card. See Add media in the editor for the full flow.

What happens next

Images in the Media Library are staged until they are used and the content publishes. When you publish a content item, Acrosite commits the images it references into your repository's media folder, then triggers a redeploy.

Developer note
Media is committed to the project's media folder (by default public/images). Make sure your site serves images from that location, or maps it during your build.

Troubleshooting

  • My upload was rejected. Check the format (JPG, PNG, WebP, AVIF, or GIF) and that the file is 10 MB or smaller.
  • I hit a media limit. Each plan limits how many images the workspace can store. Remove images you no longer use, or review your plan in Billing, trial, and plan limits.
  • An image is missing on the live site. Confirm the content item published successfully in Publish Logs, and that your site reads images from the media folder.
  • An external image broke. Images added by URL depend on that external host staying online; upload important images to the Media Library instead.