Jekyll One

QuickSearch

YAML Quick Reference (Cheat Sheet) for Jekyll data files, page front matters and collections.

Comments, blank lines or spaces

YAML, contrasting to JSON, let’s you use comments on your datablocks. To make your data more human readable, blank lines or spaces can be used.

Example themes.yml
#########################################
# Dr Jekyll's Themes - Add Your Theme!
#
- title:          Bootstrap
  github:         drjekyllthemes/jekyll-bootstrap-theme
  branch:         gh-pages
  author:         Edward Hyde
  thumbnail:      drjekyll-bootstrap.jpg
  license:        Public Domain
# Another possible formatting style could be like this
#
- title:          Classics Book
  github:         drjekyllthemes/jekyll-book-theme
  branch:         gh-pages
  author:         Edward Hyde
  thumbnail:      drjekyll-book.jpg
  license:        Public Domain

is the same as:

- title:          Bootstrap
  github:         drjekyllthemes/jekyll-bootstrap-theme
  branch:         gh-pages
  author:         Edward Hyde
  thumbnail:      drjekyll-bootstrap.jpg
  license:        Public Domain
- title:          Classics Book
  github:         drjekyllthemes/jekyll-book-theme
  branch:         gh-pages
  author:         Edward Hyde
  thumbnail:      drjekyll-book.jpg
  license:        Public Domain
The colon (:) key/value separator MUST (only) be followed by a space, thus, you can use title : Classics Books and so on. The number sign / hash (#) used for inline end-of-line comments MUST have both a leading and trailing space e.g. some text here # comment starts here, otherwise the number sign / hash is just part of the string e.g. Jekyll - The #1 Static Site Generator works as expected.

Strings or Keys without quotes

Let’s you use strings or keys without (requiring) quotes

title:            Bootstrap
github:           drjekyllthemes/jekyll-bootstrap-theme
author:           Edward Hyde

is the same as:

"title":          "Bootstrap"
"github":         "drjekyllthemes/jekyll-bootstrap-theme"
"author":         "Edward Hyde"

When to use quotes for your strings

If your string includes a colon (:) you MUST quote your string. Otherwise, the colon is interpreted as a key-value separator (e.g. key:value).

Example
title:            "Text Processing with Ruby: Extract Value from the Data That Surrounds You"
title:            "Sinatra: Up and Running - Ruby for the Web, Simply"
title:            "Using JRuby: Bringing Ruby to Java"

Note: You can quote your strings using double quotes ("") e.g. "Using JRuby: Bringing Ruby to Java" or single quotes('') e.g. 'Using JRuby: Bringing Ruby to Java'.

Data File Examples

  • List of key-value records

  • Nested List of key-value records

  • Hash (Dictionary) of key-value records

  • Multi-File List of key-value records

You can browse the examples live in action at the Sandbox Example Site at Planet Jekyll. See the start page or the sandbox site sources.

To verify and/convert your YAML data structures, check the Online YAML Parser.

List of key-value records

Book List Example: books.yml
- title:          "Text Processing with Ruby:
                  Extract Value from the Data That Surrounds You"
  author:         Rob Miller
  cover:          2015/text-processing-with-ruby.jpg
  publisher:      Pragmatic Bookshelf
  date:           Nov 2015
  pages:          200 pages (est)
  book_url:       https://pragprog.com/book/rmtpruby/text-processing-with-ruby
- title:          Learn Ruby the Hard Way
  subtitle:       A Simple and Idiomatic Intro to the Imaginative World Of Computational Thinking with Code
  edition:        3rd Edition
  author:         Zed Shaw
  cover:          2014/learn-ruby-the-hard-way.jpg
  publisher:      Addison-Wesley Professional (Zed Shaw's Hard Way Series)
  date:           Dec 2014
  pages:          336 pages
  book_url:       https://www.informit.com/store/learn-ruby-the-hard-way
- title:          "Sinatra: Up and Running - Ruby for the Web, Simply"
  author:         Alan Harris, Konstantin Haase
  cover:          2011/sinatra-up-and-running.jpg
  publisher:      O'Reilly Media
  date:           Dec 2011
  pages:          122 pages
  book_url:       https://shop.oreilly.com/product/0636920019664.do

Use like:

Nested list of key-value records

Navigation Menu Example: nav.yml
- title:          Home
  href:           /
- title:          Learn
  href:           /learning-resources/
  subcategories:
  - title:        Learning topic one
    href:         /learn1/
  - title:        Learning topic two
    href:         /learn2/
  - title:        Learning topic three
    href:         /learn3/
- title:          Tools
  subcategories:
  - title:        Tools one
    href:         /tools1/
  - title:        Tools two
    href:         /tools2/
- title:          About Us
  href:         /about-us/

Use like:

  <nav>
    <ul>
    </ul>
  </nav>

Hash (Dictionary) of key-value records

Author List Example: authors.yml
henry:
  name:           Dr Henry Jekyll
  twitter:        henryjekyll
edward:
  name:           Edward Hyde
  twitter:        edhyde

Use like:

Example 1) Lookup author info in a post

  ---
  title:  A Strange Case
  author: henry
  ---
  <a href="https://twitter.com/">
  </a>

Multi-File list of key-value records

Note: You can place data files in (sub)folders of the _data folder. Each folder level will get added to the variable’s namespace e.g. site.data.orgs.

Org Example #1: orgs/jekyll.yml
name:             Jekyll
github:           jekyll
members:
- name:           Parker Moore
  github:         parkr
- name:           Jordon Bedwell
  github:         envygeeks
Org Example #2 orgs/octopress.yml
name:             Octopress
github:           octopress
members:
- name:           Brandon Mathis
  github:         imathis

Use like:

  <ul>
  </ul>

Front Matter Examples

List of key-value records • Multi-File List of key-value records w/ Collections

List of key-value records

Portfolio Example, Part 1/2 (Front Matter) portfolio.html:

  ---
  layout:         default
  title:          Histories, Tragedies and Comedies
  portfolio:
  - title:        Richard II
    category:     History
    cover:        richard-ii.jpg
  - title:        Henry VI, Part 1
    category:     History
    cover:        henry-vi-1.jpg
  - title:        Romeo and Juliet
    category:     Tragedy
    cover:        romeo-n-juliet.jpg
  - title:        Hamlet
    category:     Tragedy
    cover:        hamlet.gif
  - title:        Antony and Cleopatra
    category:     Tragedy
    cover:        antony-n-cleopatra.jpg
  - title:        All's Well That Ends Well
    author:       Comedy
    cover:        alls-well-that-ends-well.jpg
  - title:        A Midsummer Night's Dream
    author:       Comedy
    cover:        a-midsummer-nights-dream.jpg
  ---

Use like:

Portfolio Example, Part 2/2 (Continued) portfolio.html:

  <h1>YAML Quick Reference
  <div class='porfolio'>
  </div>
The portfolio is defined inside the page (in the front matter), thus, use page.portfolio instead of site.data.portfolio to reference (e.g. loop over) the list.

Multi-File list of key-value records

Albums Example #1 _albums/josquin.html
  ---
  title:          "Josquin: Missa De beata virgine and Missa Ave maris stella"
  artist:         "The Tallis Scholars"
  director:       "Peter Phillips"
  works:
  - title:        "Missa De beata virgine"
    composer:     "Josquin des Prez"
    tracks:
    - title:      "Kyrie"
      duration:   "4:25"
    - title:      "Gloria"
      duration:   "9:53"
    - title:      "Credo"
      duration:   "9:09"
    - title:      "Sanctus & Benedictus"
      duration:   "7:47"
    - title:      "Agnus Dei I, II & III"
      duration:   "6:49"
  ---

Use like:

Example Catalog catalog.html
  ---
  layout:         default
  title:          Album Catalog
  ---

Note: Using collections you can access ALL front matters from all files from anywhere (not just inside a collection page) using the collection name e.g. site.albums.

Multi-Line Strings

Quite often, especially for to use of Jekyll, longer sequences of text or code are used. To make those better human readable, the sequence can be broken down in multi-Line strings.

Unfolded

Use unfolded multi-Line strings by keeping newlines by using |.

text: |
                  There once was a short man from Ealing
                  Who got on a bus to Darjeeling
                     It said on the door
                     "Please don't spit on the floor"
                  So he carefully spat on the ceiling

The leading indent (of the first line) and trailing white space gets stripped e.g. becoming:

  There once was a short man from Ealing\n
  Who got on a bus to Darjeeling\n
      It said on the door\n
      "Please don't spit on the floor"\n
  So he carefully spat on the ceiling\n

Folded

Use folded multi-Line strings by stripping newlines by using >.

text: >
                  Wrapped text
                  will be folded
                  into a single
                  paragraph
                  Blank lines  denote
                  paragraph breaks

Folded text converts newlines to spaces and removes leading whitespaces. The example becomes:

  Wrapped text will be folded into a single paragraph\n
  \n
  Blank lines denote paragraph breaks\n

Inline Style a.k.a. JSON-Style

As an alternative syntax you can use the inline style for lists (e.g. JSON arrays) and hashes (dictionaries, JSON objects).

Example
[
  { "title":      "Bootstrap",
   "github":      "drjekyllthemes/jekyll-bootstrap-theme",
   "author":      "Edward Hyde",
   "thumbnail":   "drjekyll-bootstrap.jpg" },
  { "title":      "Classics Book",
   "github":      "drjekyllthemes/jekyll-book-theme",
   "author":      "Edward Hyde",
   "thumbnail":   "drjekyll-book.jpg"
  }
]

is the same as:

[
 { "title": Bootstrap", "github": "drjekyllthemes/jekyll-bootstrap-theme", "author": "Edward Hyde", "thumbnail": "drjekyll-bootstrap.jpg" },
 { "title": "Classics Book", "github": "drjekyllthemes/jekyll-book-theme", "author": "Edward Hyde", "thumbnail": "drjekyll-book.jpg" }
]

or the same as:

- title:          Bootstrap
  github:         drjekyllthemes/jekyll-bootstrap-theme
  author:         Edward Hyde
  thumbnail:      drjekyll-bootstrap.jpg
- title:          Classics Book
  github:         drjekyllthemes/jekyll-book-theme
  author:         Edward Hyde
  thumbnail:      drjekyll-book.jpg

The JavaScript Object Notation (JSON) is a just another (welcome and working) formatting style for datafiles.

Literal Keys

You can use upper case letters in your keys (e.g. Teams), add spaces (e.g. Bundesliga Teams) and even start with numbers (e.g. 18 Teams).

Example
18 Teams:
  - Austria Wien
  - SC Salzburg
  - Sturm Graz

More Gotchas

  • Don’t use tabs for indentation. Use spaces instead. Always use spaces for indentation. Make sure no tabs (\t) have somehow ended up in your datafile leading to prevent unexpected results.

  • Use predefined boolean constants. The boolean true and false constants are:

true, True, TRUE
y, Y, yes, YES, YES
on, ON, ON
false, False, FALSE
n, N, no, No, NO
off, Off, OFF

All of them will become boolean values e.g. true or false.

recommend: Yes       # note: will become => true (boolean)

If you want end-up with a string make sure you use a quoted version like so:

recommend: "Yes"     # note: will become => "Yes" (string)

The same holds for the no value null constants:

~
null, Null, NULL

All of those become null, the no value. A key without a value will end-up with a null value and not an empty string. To get an empty string use double quotes "":

key1:           # note: value will become => null (no value); same as key1: null  or key1: ~
key2: ""        # note: value will become => "" (string)

Online Tools

Some handy tools are available online on the Internet. Try out the following example sites to check the validity of your YAML data code.

  • The YAML Linter. Paste in your YAML and click Go. The linter will tell you if your data is valid or not, and print out a nice clean formatted version in UTF-8.

  • The YAML Parser. Verify and convert your YAML data structures e.g. into JSON.

  • The YAML Formatter. Verify your YAML data structures even from a file.

The YAML Linter tool will add a tree-dashes-line on top of the linted (and beautified) data. This line is used to indicate the following data as YAML as used in the Ruby language.
Be careful using YAML data validators/beautifiers on your (personal) styled YAML files. A beautifier may destroy your formatting by replacing your tags by a machine readable format for faster loading and processing.