How to create assertion in Jekyll

Question

I am operating a website where we publish medical information that needs to be reviewed. We manage everything using Jekyll+Markdown+Front matter+GitHub Pages because we're cool like that.

Now we have a business requirement that every page on our website must include a front matter variable "required_reviews" to track our workflow of reviewing the content if needed. (Value is "medical review" or "none".)

Is there some way that I can create an assertion where Jekyll will crash if a page has required_reviews == ""?

question from:https://stackoverflow.com/questions/65904200/how-to-create-assertion-in-jekyll

Answer 1

To perform this kind of validation that forces a Jekyll build to fail would require a custom plugin, so the ability to do that would depend on how you're using GitHub pages: To build and host, or to host only?

If you are using GitHub pages for building the website for you (i.e. you check-in the Jekyll code and markdown, and GitHub generates the HTML/CSS/JS, etc. automatically), then it cannot be done, because GitHub does not support custom plugins. You'd have to create a separate process that you can run locally to validate the files directly.

If you are using GitHub pages only for hosting only (i.e. you build your site on a machine you can control, and only check-in the generated HTML/CSS/JS to GitHub pages) then you could use a Generator or a Liquid filter.

The main difference is that with a generator you can analyze all files, collect all the errors found, and then show all the errors you found across all pages. A generator would look something this (example / untested code):

module RequiredReviewModule

  class RequiredReviewGenerator < Jekyll::Generator
    def generate(site)

      errors = Array.new

      site.posts.docs.each do |p|
        unless p.data['required_reviews'].any? {
           errors = "On #{p.title}:  is missing"
        }
      end

      errors.each do |error|
        puts error
      end

      raise "Validation errors occurred"
    end
  end
end

A Liquid filter, you would invoke it from the liquid template with an error message that is then used to raise an exception (example / untested code):

module Jekyll
  module RequiredReviewsFilter
    def raise_error(msg)
        invalid_file = @context.registers[:page]['path']
        err_msg = "On #{invalid_file}: #{msg}"
      raise err_msg
    end
  end
end

Liquid::Template.register_filter(Jekyll::ExceptionFilter)

From your template you would check the field and call your Liquid filter in order to cause the build to fail:

{% unless page.required_reviews %}
    {{ "The field required_reviews is required" | raise_error }}
{% endunless %}

One important aspect of using a Liquid filter is that the build will stop as soon as it finds the first page that doesn't have the required_reviews field, so if you prefer to see all the errors at once, then the Generator would be the way to go.