Skip to content

TOP012.md

Latest commit

 

History

History
85 lines (49 loc) · 2.5 KB

TOP012.md

File metadata and controls

85 lines (49 loc) · 2.5 KB

TOP012 - Heading levels

Tags: headings

Aliases: heading-levels

Fixable via script: The fix script can fix incorrect heading levels but of course cannot add missing headings.

This rule is triggered when either:

  • A note box either does not have a heading.
  • A note box has a heading but it is not a level 4 (####) heading, which is required by our layout style guide.
  • The assignment section contains a subheading but it is not a level 4 (####) heading, which would be semantically incorrect.
<div class="lesson-note" markdown="1">

No heading will flag a TOP012 error.

</div>
<div class="lesson-note" markdown="1">

### Non-level 4 note box heading: Will flag a TOP012 error as it should be level 4

Note box contents.

</div>

These can be resolved either by adding a level 4 heading or changing the note box heading to a level 4:

<div class="lesson-note" markdown="1">

#### Level 4 note box heading: Correct and will not flag a TOP012 error

Note box contents.

</div>

The same applies to subheadings within an assignment section that are not level 4.

Incorrect level:

### Assignment

<div class="lesson-content__panel" markdown="1">

### Semantically incorrect level for a section subheading

Contents

</div>

Correct level:

### Assignment

<div class="lesson-content__panel" markdown="1">

#### Semantically incorrect level for a section subheading

Contents

</div>

If the error is about the heading level, it is fixable with our fix npm script, which will convert the heading to be at level 4. The fix script cannot do anything about missing headings.

Rationale

Headings within an assignment section are semantically subheadings of that section, not headings for separate sibling sections. Since the assignment section is at level 3, its subheadings must be at level 4.

Headings also have IDs that can be linked to. Given the nature of note boxes, enforcing headings for them allows all of them to be more easily linked, while the heading also summarizes the note's intent.

Consistent use of heading levels for note boxes also looks better on the website, and is less confusing as note boxes are not main sections themselves, so they should not use a level 3 heading.

The website also uses specific CSS for when note box headings are hovered over. Having non-level 4 headings in these note boxes causes behavior inconsistent with what we expect.
⚡