TOP004 - Lesson headings

Tags: headings

Aliases: lesson-headings

Fixable via script: Not fixable due to being context-based

The rule is triggered when the headings in the document do not match the specified list of required headings. It compares each heading in the document with the corresponding required heading and reports any mismatches.

Currently, the required headings depend on the content's type:

Lesson headings structure

### Introduction
### Lesson overview
### A custom heading
* (Wildcard: Any heading at any level)
### Assignment
* (Wildcard: Any heading at any level)
### Knowledge check
### Additional resources (optional)

The wildcard symbol * represents any heading text at any level. This means that any heading will be considered valid, regardless of its actual text content.

The Additional Resources section should only be present if it contains resources. If it is empty, the section should not be present at all.

Project headings structure

### Introduction
* (Wildcard: Any heading at any level)
### Assignment
* (Wildcard: Any heading at any level)

Similar to the lesson headings structure, the wildcard symbol * in the project headings structure allows for any heading text at the specified level.

Guide headings structure

### Guide: * (Any descriptive title)
* (Wildcard: Any heading at any level)

Guide files are reference content stored in folders ending with _guides (e.g., installation_guides/). They must start with a heading beginning with ### Guide: followed by a descriptive title. After that, any heading structure is allowed since guides are flexible instructional content.

Files located in *_guides/ folders automatically use this guide structure instead of the lesson or project structure.

Exceptions

There are a few lessons where it does not make sense to enforce any particular heading structure, such as course intro lessons or course conclusions. Lessons with the following file names are exempt from this rule:

• how_this_course_will_work.md
• conclusion.md
• conclusion_full_stack_javascript.md
• conclusion_ruby_on_rails.md

Rationale

Enforcing a consistent heading structure improves readability, organization, and navigation. By specifying a required heading structure, authors can ensure that their documents follow a standardized format and include all the necessary sections. This rule helps maintain consistency across multiple documents and makes it easier for readers to locate specific information.