Configuring uploads

Upload Directory

Keep a consistent file structure by setting up an uploads path structure. Images, documents, and other files in the editor are uploaded to this location.

  image: # Front matter field
    uploads_dir: "uploads/front-matter-images/:title"
  content: # Content Editor and block Editable Regions
    uploads_dir: "uploads/:year/:month/:day/:title"

The :categories and :title dynamic fields resolve to the associated front matter fields for the containing file. :year, :month, and :day are obtained from the date front matter field for the containing file.

Set uploads_dir in your _config.yml to set it everywhere:

uploads_dir: "uploads/:categories/:year/:month/:day/:title"

Image Uploads

Control the size and format of images clients or team members upload through the interface. Images are resized and converted automatically.

Set options for images uploaded with the Content Editor and block element Editable Regions using the content key. Options for inputs in front matter or data files are specified by matching key names.

    width: 90
    height: 120
    resize_style: "contain"
    mime_type: "image/jpeg"
    expandable: true
    width: 90
    height: 120
    resize_style: "cover"
    mime_type: "image/png"
width - Integer

Defines the width of the bounding box

height - Integer

Defines the height of the bounding box

resize_style - String, one of contain, cover or stretch (optional, defaults to contain)

Defines how uploaded images are resized with respect to that box:

  • cover ensures the image covers the bounding box
  • contain ensures the image fits inside the bounding box
  • stretch ignores aspect ratio to resize the image to the bounding box
mime_type - String, one of image/jpeg, image/png (optional, defaults to uploaded type if supported)

Sets what format the image is converted into on upload.

expandable - Boolean (optional, defaults to false)

Set to true allows images to be enlarged past original dimensions.

Restricting file types

Restrict which files types editors can upload for specific inputs with the accepts_mime_types option.

For example, to make it so editors can only upload png and svg files in the featured_image field of each blog post:

      - "image/png"
      - "image/svg+xml"

Not setting the accepts_mime_type option allows all files of the appropriate type within the field. For example, in an image field an editor could upload any image with a valid image extension (.jpg, .jpeg, .png, etc.).

Was this article helpful? or Suggest an improvement >