Choose your preferred SSG:
Choose your preferred SSG:

Using file path inputs to edit your data

These inputs allow editors to upload new files, select existing images, and add external links. Enterprise customers can even configure an external digital asset manager for their team.

File

File select input with controls to enter external links and upload new files. Does not filter by file type when choosing files.

File inputs are shown for inputs configured with the type file, or for input keys matching:

  • path
  • *_path
Screenshot of file input field with a CSS file selected
Naming convention
extra_styles_path: /styles/screen.css
Input configuration
path_to_css: /styles/screen.css
_inputs:
  path_to_css:
    type: file

Image

Image select inputs with controls to enter external links and upload new image files. Filters files available to choose to files with image extensions.

Image inputs are shown for inputs configured with the type image, or for input keys matching:

  • image
  • *_image
  • image_path
  • *_image_path
Screenshot of image upload field with an image file selected
Naming convention
background_image_path: /images/background.png
Input configuration
image_file: /images/background.png
_inputs:
  image_file:
    type: image

Document

Document select inputs with controls to enter external links and upload new document files. Filters files available to choose to files with document extensions.

Document inputs are shown for inputs configured with the type document, or for input keys matching:

  • document
  • *_document
  • document_path
  • *_document_path
Screenshot of Document input field with a PDF file selected
Naming convention
newsletter_document_path: /documents/2016/newsletter.pdf
Input configuration
path_to_newsletter: /documents/2016/newsletter.pdf
_inputs:
  path_to_newsletter:
    type: document

Options

File path inputs are configured with options inside an _inputs entry.

Input configuration
image_file: /uploads/image.png
_inputs:
  image_file:
    type: file
    options:
      uploads_dir: uploads
      accepts_mime_types:
        - image/png
        - image/svg+xml
        - image/jpeg
      width: 400
      height: 300
      resize_style: cover
      mime_type: image/jpeg
      expandable: true
      correct_orientation: false

File path inputs have the following options available:

uploads_dir - String

Sets where new uploaded files are stored within your site. Defaults to the paths.uploads in global configuration, which is uploads if unset.

uploads_dir has dynamic placeholders available. Placeholders can result in empty values and sequential slashes are collapsed into one after applying placeholders. The available placeholders are:

  • :categories and :title from the front matter or data of the containing file
  • :year, :month, and :day from the date front matter or data of the containing file
  • :collection resolves to the collection key the containing file belongs to
accepts_mime_types - String or array of strings

Restricts which file types are available to select or upload to this input. Optional, each file path input has a different default:

  • File: *
  • Image: image/x-icon,image/gif,image/jpeg,image/jpeg,image/png,image/webp,image/bmp,image/svg+xml
  • Document: application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-powerpoint,application/vnd.openxmlformats-officedocument.presentationml.presentation

If set as a string, the value should be a comma-separated (no spaces) list of the mime types you want to filter by. The string * by itself allows any type.

If set as an array, each item should be a string of a single mime type you want to filter by.

If the input allows for images, the following options are also available:

width - Integer

Defines the width of the bounding box used in the resizing process defined with resize_style.

height - Integer

Defines the height of the bounding box used in the resizing process defined with resize_style.

resize_style - String

Sets how uploaded image files are resized with a bounding box defined by width and height prior to upload. Defaults to contain. Must be contain, cover or stretch:

  • cover keeps aspect ratio and ensures the image covers the bounding box
  • contain keeps aspect ratio and ensures the image fits inside the bounding box
  • stretch ignores aspect ratio and resizes the image to the bounding box

Has no effect when selecting existing images, or if width and height are not set.

mime_type - String

Sets what format the image is converted to prior to upload. The extension of the file is updated to match. Defaults to keeping the mime type of the uploaded file. Must be one of image/jpeg or image/png.

expandable - Boolean

Controls whether or not images can be upscaled to fit the bounding box during resize prior to upload. Defaults to false. Has no effect if files are not resized.

correct_orientation - Boolean

Controls whether or not the JPEG headers defining how an image should be rotated before being displayed is baked into the image prior to upload. Defaults to true.

Was this article helpful? or Suggest an improvement >