Uploading images
The media library is where all images and videos on your site live. Uploading a file adds it to your library so you can place it in any Media section — or swap it in later without re-uploading.
How to open the upload area
Section titled “How to open the upload area”Open the media library from any Media section in the editor. The upload area appears at the top of the panel that slides open.
Uploading a file
Section titled “Uploading a file”You have two options:
- Drag and drop — drag one or more files from your desktop and drop them onto the dashed upload zone.
- Click to browse — click anywhere in the upload zone to open a file picker and select files from your computer.
Both accept images (JPEG, PNG, WebP, GIF, and most other common formats), video files, and documents — PDFs and single, self-contained HTML files. A document is stored as-is: it is never converted or resized.
Uploading a whole folder
Section titled “Uploading a whole folder”If your files are already organized into folders on your computer, you can bring that structure into the library in one step:
- Click “Upload a folder” inside the dashed upload zone (just below the drag-and-drop text) to open a folder picker.
- Drag a folder from your desktop and drop it onto the upload zone, the same as dropping individual files.
Any subfolders inside are recreated as matching folders in the library, nested the same way. If you’re uploading into a folder that already contains a folder with the same name, the new files are merged into it instead of creating a duplicate.
If any files in the library already match files you’re uploading, those are skipped rather than uploaded again — you’ll see a notice such as “1 file already exists in the library and was left where it is.”
What happens after you drop a file
Section titled “What happens after you drop a file”Your browser processes the file immediately — no waiting for a server round-trip:
- The image is converted to WebP format in your browser.
- Three sizes are generated automatically: 640 px, 1 080 px, and 1 920 px wide. The right size is served to each visitor depending on their screen, so pages stay fast.
- The processed file is held locally until you save. Once you save, it is stored in your site’s GitHub repository.
After processing finishes, the image appears in the library grid below the upload zone.
File size limit
Section titled “File size limit”Files larger than 5 MB are rejected and will not upload. If a file is too large, you’ll see a notice — for a single over-limit file it names the file; if several are rejected at once, it shows how many. Compress or resize the image first, then try again.
(This limit is a default and can be adjusted by your site administrator.)
Document size limits
Section titled “Document size limits”Documents have their own limits, because they are stored differently from images:
- Up to 2.5 MB — the file is saved into your site’s repository along with everything else. Nothing extra is needed.
- Over 2.5 MB — the file goes to your site’s document storage, up to 200 MB. If document storage has not been set up yet, you’ll see a notice like “report.pdf” is over 2.5MB, and document storage isn’t set up on this site yet. — that file is skipped, everything else in the same drop still uploads, and nothing else about your site changes. Ask your site administrator to turn document storage on, or supply a smaller file.
- Over 200 MB — refused outright, with a notice naming the 200 MB document limit.
Alt text
Section titled “Alt text”Each image in the library has an alt text field directly below its thumbnail. Alt text describes the image for screen readers and search engines. Fill it in after uploading — you can update it at any time from the library.