Announcing the Lesson Validator

This post originally appeared on the Software Carpentry website.

Thanks to the work of Andy Boughton and Raniere Silva, we now have a validator that determines whether lessons fit the new lesson template. This post explains what it does, where there is room for improvement, and how you can help.

Current State

The validator uses Python's CommonMark parser to create an abstract syntax tree from a Markdown file. This allows our code to focus on validating templates, rather than re-implementing a parser that can handle variations in Markdown.

Because each template has slightly different needs, the validator is implemented using an object-oriented approach that allows individual tests to be customized or re-used as needed. Each template validator class is a child of MarkdownValidator, so to understand how the validator works for pages/LICENSE.md, you just need to look at the special methods in LicensePageValidator, and whatever code is inherited or used from the parent class MarkdownValidator.

What Validation is Performed

The validator currently performs the following checks on all templates:

• All expected YAML document headers must be present and contain the correct type of data (e.g. the argument for minutes must be numeric).
• All headings required by the template must be present, and in the correct order.
• All document headings must be level 2 (i.e. ## Heading).
• If the template is not free-form, then only the headings specified should be present.
• Links to external assets (html pages or images) must be valid.

Additional checks are performed on certain templates as needed:

• Special blocks (such as Prerequisites and Learning Objectives) must have the correct structure and contents.
• The glossary in pages/reference.md must be formatted correctly.
• The pages/LICENSE.md file must not be changed.

How You Can Help

• Summarize the changes to the specifications (see below).
• Test the validator on a folder full of markdown files from the command line: $ tools/check pages/. Let us know if the validator is too restrictive for your lessons, or if it misses a common problem.
• Report suggestions and bugs on GitHub.
• Send pull requests to improve the code.

Lesson Template Specification

Several of the core Software Carpentry lessons have recently been ported to the new template. As we apply the template to lessons, the original template specification has continued to evolve—see the lesson template's repository for the latest description. The validator reflects these changes.

For example, authors no longer need to specify CSS styles in topic files, so we can write:

> ## Learning Objectives
>
> * Learning objective 1
> * Learning objective 2

instead of:

> ## Learning Objectives {.objectives}
>
> * Learning objective 1
> * Learning objective 2