Editing

Options

Available for Jekyll sites.

Configure the various editing interfaces for your clients to optimise for their specific needs. Options can be set for keys matching the same name in three ways:

  • Globally in _config.yml
  • File specific in front matter
  • Custom scope with Jekyll Defaults

Hidden Fields

Control which front matter fields your editors see with the hidden option.

_options:
  layout:
    hidden: true

Hidden fields can be edited with modal-style Editor Links.

Alternatively, hide front matter fields by prefixing the key with an underscore (e.g. _hidden_text).

Toolbars

Control the toolbar options for your clients or editors to increase focus on the content at hand.

Set toolbar options for the Content Editor with the content key, and Editable Regions using the _block and _text keys. Options for Rich Text front matter interfaces are specified by matching key names.

_options:
  some_markdown:
    bold: true
    table: true
  _text:
    italic: true
  _block:
    format: p h3
    undo: true
    redo: true
  content:
    format: p h1 h2 h3 h4 h5 h6 pre address div
    bold: true
    numberedlist: true
    code: true
    table: true
    right: align-to-right
    styles: /_sass/_content-typography.scss
    embed: true

You can also set options directly on elements for Editable Regions:

<p class="editable" data-cms-options='{"bold": true, "italic": true}'>...</p>

The most specific options that apply to an interface are used, less specific options that still apply are ignored. In order of specificity: data-cms-options attributes, front matter and Jekyll defaults, then globally in _config.yml.

The complete list of options follows, all values can either be true or false unless specified otherwise:

Option Values
bold  
italic  
removeformat  
link  
undo  
redo  
underline  
strike  
subscript  
superscript  
code (unavailable for _text)  
format (unavailable for _text) true, false or space separated options
blockquote (unavailable for _text)  
numberedlist (unavailable for _text)  
bulletedlist (unavailable for _text)  
outdent (unavailable for _text)  
indent (unavailable for _text)  
image (unavailable for _text or Rich Text fields)  
embed (unavailable for _text or Rich Text fields)  
table (unavailable for _text)  
styles (unavailable for _text) false, or path to source CSS file
left (unavailable for _text) false or string of class name
center (unavailable for _text) false or string of class name
right (unavailable for _text) false or string of class name
justify (unavailable for _text) false or string of class name

Embedding Media

Allow your editors to embed YouTube, Vimeo, Tweets and other media into their content. Embedded content is sanitised to mitigate XSS risks, which includes removing style and script tags.

_options:
  content:
    embed: true

Add the scripts to the end of pages where embedded content is added to enable the same behaviour (e.g. link the Twitter script that transforms blockquotes into Tweets when a front matter field is true).

Styles

Add predefined styles in plain CSS for your clients and team members to use in the Visual Editor, Content Editor and Front Matter interfaces.

_options:
  content:
    styles: /css/content.css

The file can have any extension, but must contain only plain CSS and be a source file. Selectors must specify an element and one class in order to be included in the styles dropdown. Styles with incompatible selectors are included in the editor, but not shown as options.

p.callout { /* Can be applied to blocks of content */
  margin: 10px;
  border: 1px solid #f5f5f5;
  background-color: #eee;
}

span.big-blue-text { /* Can be applied to inline content */
  font-size: 2rem;
  color: blue;
}

h2 { /* Applied to content, excluded from style dropdown */
  font-family: cursive;
}

.center-this-text { /* Excluded from style dropdown, used as center class described below */
  text-align: center;
}

Custom styles in the Visual Editor requires the same styles on your live site, otherwise the class is applied but has no visual effect.

Use the justification options to specify classes for alignment rather than the dropdown for a better editing experience:

_options:
  _block:
    left: align-left
    center: center-this-text
    right: align-right
    justify: full-width-text

Be sure to include these classes in your styles CSS for them to take effect.

Code Blocks

Change the appearance and behaviour of your front matter code blocks to fit your use case and brand.

_options:
  code_block:
    tab_size: 2
    show_gutter: false
  javascript_code_block:
    tab_size: 4
    theme: dawn
Option Values
tab_size Integer (optional, defaults to 4)
theme String, one from themes (optional, defaults to monokai)
show_gutter true or false (optional, defaults to true)

tab_size controls how many spaces lines are auto indented.

theme controls the appearance of the editor.

show_gutter toggles line numbers and code folding controls.

File Uploads

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.

_options:
  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, :year, :month, :day and :title dynamic fields resolve to the associated Jekyll fields for the containing file.

You can also set site.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 front matter interfaces are specified by matching key names.

_options:
  image_path:
    width: 90
    height: 120
    resize_style: "contain"
    mime_type: "image/jpeg"
    expandable: true
  content:
    width: 90
    height: 120
    resize_style: "cover"
    mime_type: "image/png"
Option Values
width Integer
height Integer
resize_style contain, cover or stretch (optional, defaults to contain)
mime_type image/jpeg, image/png (optional, defaults to uploaded type if supported)
expandable true or false (optional, defaults to false)

mime_type sets what format the image is converted into on upload. width and height define a bounding box. resize_style 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

expandable set to true allows images to be enlarged past original dimensions.


Comments

Helper text to provide additional context. Configured globally in _config.yml or per file in front matter with a _comments object:

_comments:
  title: The page title
  output: Does this item have a dedicated page?
  brand_colour: The primary brand colour
  footer: Update the details in the footer

Alternatively, configure comments on a custom scope with Jekyll defaults:

defaults:
  - type: ''
values:
  _comments:
    title: The page title
    output: Does this item have a dedicated page?
    brand_colour: The primary brand colour
    footer: Update the details in the footer

Comments are displayed for the same keys in the _comments object.

---
_comments:
  title: The page title
  output: Does this item have a dedicated page?
  brand_colour: The primary brand colour
  footer: Update the details in the footer
---
Comments interface

Array Defaults

Provides initial values for newly created items in arrays. Configured globally in _config.yml or per file in front matter with a _defaults object:

_defaults:
  image_path: /images/placeholder.png

Alternatively, configure on a custom scope with Jekyll defaults:

defaults:
  - type: ''
values:
  _defaults:
    image_path: /images/placeholder.png

New array items clone the structure from the existing array items. Array defaults populate that structure for the same keys in _defaults.

---
_defaults:
  image_path: /images/placeholder.png
images:
  - image_path: /images/sunset.png
    title: Sunset

  # Adding an item to the array is prepopulated as:
  - image_path: /images/placeholder.png
    title:
---
Array Defaults interface
Array defaults also apply when editing CSV, YAML and JSON files.