Strict rendering
How to force an error when getting a warnig on bad Liquid or frontmatter fields
Jekyll is forgiving when you use a variable or key name or filter that does not exist. This can make debugging tricky. To stop these things failing silently, you can configure Jekyll to be stricter.
Enforce strict frontmatter
Make a build to abort if there is a syntax error in a page’s frontmatter.
In _config.yml
, set this field.
strict_front_matter: true
Liquid options
See Liquid Options in the docs.
Jekyll allows you to customize Liquid options under liquid
in _config.yml
.
This can cause your deploy or local build to abort if an undefined filter or variable is used.
Default values
Here are the default options:
liquid:
error_mode : warn
strict_filters : false
strict_variables : false
Strict settings
Set those all to strict values.
liquid:
error_mode: strict
strict_variables: true
strict_filters: true
Add strict Liquid settings so Jekyll will fail on bad syntax and give you confidence in deployed code..
Strict variables - This will prevent referencing a variable that has not been defined. Normally it would quietly appear as empty string. e.g. . Or an undefined attribute -
will give an error that the key is not set.
Strict filters - Prevent using a bad filter. e.g. text
will say filter not available instead of ignoring it quietly.
You can also change the error mode from warn
to strict
.
I don’t know why error mode needs to set and what it does - perhaps those are errors on other areas. For example, I have run my build in verbose mode before and seen warnings that didn’t stop the build.
These are mutually exclusive fields according to the docs. Though weirdly my IDE’s YAML linter doesn’t like having the both error mode and strict settings in the same file.
When strict checks are too strict
The safest is to set the values aggressively as above.
But this may be impractical. You may have issues on one or more fields caused by your code in your theme and not your actual code.
Which means you’ll have to leave out some fields covered above.
Or you adjust for it. For example, the Minima theme’s post.html
layout uses site.minima.date_format
and site.disqus.short_name
as optional config values. So to do a build, you have to set them as empty in your config, or override the layout.
And it is not safe to set the entire site.minima
to null for example, as you might affect other values used by the theme. Plus that is not actually effective because you get the error anyway on the last level.
This works though:
minima:
date_format:
disqus:
shortname:
Also set this on your index.md
and 404.html
title:
I had issues in other parts of my jekyll-blog-demo
repo so I stopped using all the strict settings.