Media

Configure where uploaded files are stored and what URLs are written.

What media does

media defines file storage for:

Use it to answer two questions:

  1. Where should uploaded files be saved in the repository?
  2. What public path should be written into content?

Shapes

You can define media as:

  • a string,
  • one object,
  • an array of named media sources.

Keys

Key Description
name ** Internal media source name. Required when using an array (e.g. "images").
label UI label for the media source (e.g. "Product images").
input * Repository path where files are stored (e.g. "src/media").
output * Public path written into content (e.g. "/media").
extensions Allowed extensions (e.g. ["png", "webp"]).
categories Category-based extension sets. Values: image, document, video, audio, compressed, code, font, spreadsheet.
rename If true, uploads get a random filename plus their original extension.
commit Per-media commit settings. See settings.commit .

*: Required
**: Required with multiple sources

Field-level media options can override the media source defaults.

String form

media: media

Equivalent to:

media:
  input: media
  output: /media

Single media object

media:
  input: src/media
  output: /media
  rename: true
  categories: [image]

Multiple media sources

Use an array when different field types should write to different folders.

media:
  - name: images
    label: Images
    input: media/images
    output: /media/images
    rename: true
    extensions: [png, jpg, webp]
  - name: docs
    label: Documents
    input: media/docs
    output: /media/docs
    categories: [document]

Commit templates

media[].commit.templates overrides the global commit templates for that media source.

media:
  - name: images
    input: media/images
    output: /media/images
    commit:
      templates:
        create: "chore(media): add {filename}"
        update: "chore(media): update {filename}"
        delete: "chore(media): remove {filename}"
        rename: "chore(media): rename {oldFilename} -> {newFilename}"
Content Image field File field