Images in a Hugo site are just files in static/, referenced by path. The media library is a modal for browsing that folder, uploading into it and picking a path to insert, so you don’t have to remember whether it was /images/2026/hero.jpg or /img/hero.jpg.
It opens from the image button in the editor toolbar, from Browse on image and file fields, and on its own when you drop or paste a single image into the editor.
Configuration#
The media block in admin/site.yaml says where files live and what’s allowed:
media:
folder: static/images
public_path: /images
max_size_mb: 10
accept:
- image/png
- image/jpeg
- image/webp
- image/gif
- image/svg+xml| Key | What it is | Default |
|---|---|---|
folder |
Where files live in the repository. Prefixed with base_path if you’ve set one. |
static/images |
public_path |
The URL prefix Hugo serves that folder at. This is what gets written into your content. | /images |
max_size_mb |
Upload size limit. | 10 |
accept |
What the library lists and accepts for upload, as MIME types or extensions such as .pdf. |
PNG, JPEG, WebP, GIF, SVG |
A file at static/images/photos/hero.jpg is inserted as /images/photos/hero.jpg. The media configuration page has the config side; the rest of this page is about using it.
Browsing#
The grid shows folders first, then files. Click a folder to go in, and the breadcrumb (which starts at the last segment of folder, so images by default) to come back out. Emet remembers the folder you were last in. The Date / Name / Size dropdown sorts the grid; on GitHub-hosted sites sorting by date means looking up each file’s last commit, so dates fill in a moment after the thumbnails do. The search box filters by name within the current folder.
On private repositories the browser can’t load images by URL, so Emet fetches them through the GitHub API and caches them. That’s why thumbnails take a second the first time and are instant after.
Inserting#
Click a file to select it; a bar appears below the grid with its name and an Alt text box. Insert, Enter in the alt text box, or a double-click on the thumbnail hands the public path and alt text back to whatever opened the library. Image and file fields take just the path.
Uploading#
Drop a file on the dashed area at the top, or click browse. The file is checked against accept and max_size_mb, then committed to the current folder with a timestamp prefix on a sanitised name, e.g. 1712150400000-my-photo.jpg, so two uploads can’t collide. It appears at the top of the grid, already selected.
When you drop or paste a single image straight into the editor, the library opens in Save image mode instead. You pick a folder, give the file a proper name (lower-cased, anything that isn’t a letter or digit becomes a hyphen, extension kept) and alt text, then click Save to this folder. Several images at once, or images inside pasted rich text, are uploaded in the background with generated names and don’t open the library at all. See Images in the visual editor.
Upload commits always carry the skip-CI suffix (Upload image: 1712150400000-my-photo.jpg [skip ci]), on the theory that an image changes no page by itself and the save of the page that uses it will trigger the build. See Sync.
Folders and renaming#
New Folder in the breadcrumb bar creates a subfolder (letters, digits, hyphens and underscores). Git can’t store an empty directory, so Emet commits a .gitkeep file into it, which the grid hides. The trash icon on a folder deletes it, but only while it’s empty apart from that placeholder, and there’s no confirmation step, so mind where you click.
The pencil icon on a file renames it, keeping the extension and refusing names already in use. The rename is one commit that removes the old path and adds the new one. Nothing updates content that referenced the old path; that’s on you.
There’s no way to delete a file from the library yet. Delete it from the repository directly, or leave it; an unreferenced image costs you nothing but repository size.
Editing with AI#
If image generation is configured and your provider supports it, selecting a file shows an Edit with AI button, which opens the image generator with that file as the reference. From an image field the result can replace the original file in place. See Image generation.