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?

Media sources can also define actions. See actions.

Value

You can define media as:

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

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]
    actions:
      - name: optimize-images
        label: Optimize images
        workflow: pages-cms-media-action.yml
  - name: docs
    label: Documents
    input: media/docs
    output: /media/docs
    categories: [document]

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 .
actions Adds media action buttons. See actions.

*: Required
**: Required with multiple sources

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

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 Actions Image field File field