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.