We’ve recently changed the way you configure inputs. Check out our migration guide here.
The Data Editor uses a wide range of different inputs. Each input corresponds to a field in your front matter or data file, providing an editing interface for those values. Inputs have a type, label and a comment.
Use the _inputs
configuration to change types, labels, comments, instance values, and specific type options. Some configuration (notably input type) is automatically set for you based on the input key.
_inputs:
my_custom_input:
type: image
label: Hero Image
comment: Appears at the top of the page
options:
width: 720
height: 480
resize_style: cover
[_inputs.my_custom_input]
type = "image"
label = "Hero Image"
comment = "Appears at the top of the page"
[_inputs.my_custom_input.options]
width = 720
height = 480
resize_style = "cover"
{
"_inputs": {
"my_custom_input": {
"type": "image",
"label": "Hero Image",
"comment": "Appears at the top of the page",
"options": {
"width": 720,
"height": 480,
"resize_style": "cover"
}
}
}
}
The above code shows the _inputs
configuration set in the same file, but you can choose where to set this for inputs across your site in the configuration cascade.
Each key inside _inputs
targets one or more inputs in the Data Editor. These keys can target inputs directly by key name, or the nested path to the input.
This configuration applies to title
inputs:
title: Main page title
_inputs:
title:
type: text
comment: Large text at the top of the page
title = "Main page title"
[_inputs.title]
type = "text"
comment = "Large text at the top of the page"
{
"title": "Main page title",
"_inputs": {
"title": {
"type": "text",
"comment": "Large text at the top of the page"
}
}
}
This configuration applies to date
inputs at the root level of your data only:
title: Main page title
nested:
title: This input does not have the comment
_inputs:
$.title:
comment: Large text at the top of the page
title = "Main page title"
[nested]
title = "This input does not have the comment"
[inputs."$.title"]
comment = "Large text at the top of the page"
{
"title": "Main page title",
"nested": {
"title": "This input does not have the comment"
},
"_inputs": {
"$.title": {
"comment": "Large text at the top of the page"
}
}
}
This configuration applies to title
inputs directly inside seo
objects:
title: This input does not have the comment
seo:
title: Longer title for search engines
_inputs:
seo.title:
comment: Summary of this page for search engines
title = "This input does not have the comment"
[seo]
title = "Longer title for search engines"
[_inputs."seo.title"]
comment = "Summary of this page for search engines"
{
"title": "This input does not have the comment",
"seo": {
"title": "Longer title for search engines"
},
"_inputs": {
"seo.title": {
"comment": "Summary of this page for search engines"
}
}
}
This configuration applies to image
inputs inside card
array items:
cards:
- image: /uploads/jane.png
_inputs:
cards[*].image:
type: image
options:
width: 100
height: 100
[[cards]]
image = "/uploads/jane.png"
[_inputs."cards[*].image"]
type = "image"
[_inputs."cards[*].image".options]
width = 100
height = 100
{
"cards": [
{
"image": "/uploads/jane.png"
}
],
"_inputs": {
"cards[*].image": {
"type": "image",
"options": {
"width": 100,
"height": 100
}
}
}
}
This configuration applies to inline images
array items:
images:
- /uploads/jane.png
_inputs:
images[*]:
type: image
options:
width: 100
height: 100
images = [ "/uploads/jane.png" ]
[_inputs."images[*]"]
type = "image"
[_inputs."images[*]".options]
width = 100
height = 100
{
"images": [
"/uploads/jane.png"
],
"_inputs": {
"images[*]": {
"type": "image",
"options": {
"width": 100,
"height": 100
}
}
}
}
Read more on configuring inline array inputs.
These selector-style keys can be as targeted as you need them to be:
author
targets author
inputs anywhere.seo.another.title
targets title
inputs, directly inside another
objects, directly inside seo
objects.$.blocks[*].author.title
targets title
inputs, directly inside author
objects, directly inside blocks
array items, where blocks
is at the root level.Each entry in _inputs
has the following options available:
type
- String
Changes the editing interface for an input. Each input appears and behave differently, takes different options
, and processes different values. See more details in the type section below.
For unknown types, or if the input contains an unsupported value (e.g. an array value in a text input), the disabled
type is used instead.
label
- String
Changes the text above an input. Defaults to generating the label from the input key (e.g. “Page Title” for page_title
).
comment
- String
Changes the subtext below the label
. Has no default. Supports a limited set of Markdown: links, bold, italic, subscript, superscript and inline code elements are allowed.
Useful for adding reminders or additional context for your team members on a specific input.
options
- Object
Configuration settings passed on to the input when displayed. These are specific to each input. The available types and their options are listed below.
instance_value
- String
Controls if and how the value of this input is instantiated when created. This occurs when creating files, or adding array items containing the configured input. Has no default. Must be one of UUID
or NOW
.
UUID
generates a uuidv4 (extremely unlikely to generate duplicates), useful for identifying unique items (e.g. 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b
)NOW
generates the current datetime in the site’s configured timezonehidden
- Boolean or string
Toggles the visibility of this input. Useful for when you need an input to exist, but don’t want it edited or seen. Defaults to the naming convention, true
for input keys starting with an underscore and false
otherwise.
If set as a boolean, the input is hidden based if true
.
If set as a string, the input is hidden based on the value of another input. This can start with a !
to reverse the value.
published
hides an input when the sibling input published
is truthy!published
hides an input when the sibling input published
is falsycascade
- Boolean
Specifies whether or not this input configuration should be merged with any matching, less specific configuration. Defaults to true
.
The configuration cascade works by finding the most specific _inputs
entry. Usually, once an option is found in the cascade, there’s no reason to keep looking.
When this is true
, the cascade continues looking and each entry found is merged. This allows you to define a comment
globally, then a different label
for inputs in a collection without redefining the comment
. You can stop the cascade at any given point by setting cascade
to false
.
The type defines how inputs appear and behave. The type used for each field is based on (in order):
type
in _inputs
for that keycolor
will give you a color picker)This results in good defaults for unconfigured inputs, without hindering configured inputs. To change the type for an input you can use the _inputs
configuration, or the naming conventions:
my_custom_input:
_inputs:
my_custom_input:
type: image
color: '#efefef'
some_text: Hello
my_custom_input = ""
[_inputs.my_custom_input]
type = "image"
color = "#efefef"
some_text = "Hello"
{
"my_custom_input": "",
"_inputs": {
"my_custom_input": {
"type": "image"
}
}
}
{
"color": "#efefef",
"some_text": "Hello"
}
The naming conventions support snake_case
, camelCase
, PascalCase
and kebab-case
.
Here are all the available input types, each with their own available options:
text
textarea
email
disabled
pinterest
facebook
twitter
github
instagram
code
checkbox
switch
color
number
range
url
html
markdown
date
datetime
time
file
image
document
select
multiselect
choice
multichoice
object
array