Announcing the Lesson Validator
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
minutesmust 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.mdmust be formatted correctly. - The
pages/LICENSE.mdfile 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