Published 2024-07-23.
Time to read: 1 minutes.
jekyll collection.
Jekyll websites use YAML to identify pages that should be interpreted with the Liquid templating language. The YAML is placed at the top of the page, and is referred to as front matter.
Sometimes while I am writing a Jekyll page a bizarre error message suddenly appears.
If the message mentions the Psych module, then the cause is malformed YAML.
Here is one such error message:
/
The problem might be one or more missing colons. For example, instead of this:
--- title One Fine Day ---
A colon is required to set off the key from the value:
---
title: One Fine Day
---
Here is another error message:
Psych::SyntaxError on line 1 of /
The problem is likely a quoting problem in the front matter of a page. For example:
---
title: It's a Fine Day
---
Quotes are required encapsulate the value:
--- title: "It's a Fine Day" ---
The problem might be leading whitespace before a key. For example:
---
title: Space before a key is not allowed
---
Identifying Problematic Front Matter
If you are unsure which page might be problematic, following is a short Ruby program that reads every HTML and markdown file, extracts the front matter, and checks the YAML in the front matter for validity.
If the program runs to completion, all your source files have well-formed front matter.
#!/usr/bin/env ruby
require 'yaml'
class String
def front_matter
self[/(---\n.*?)---\n/m, 1]
end
end
entries = Dir['collections/**/*.(html,md)']
.reject { |fn| File.directory?(fn) }
entries.each do |entry|
puts "Reading #{entry}"
yaml = File.read entry
puts "Reading #{entry} front matter"
front_matter = yaml.front_matter
puts "Front matter for #{entry} is:\n#{front_matter}"
puts "Converting front matter in #{entry} to YAML"
YAML.unsafe_load front_matter
end
identify_problem_front_matter needs to be made executable:
$ chmod a+x identify_problem_front_matter
The program can be verbose, so you might want to view the output by piping it through a pager, such as less:
$ identify_problem_front_matter | less
