Do you use headings in GitHub issues and PRs? Chances are that you are using the wrong level.

TL;DR: Use heading level 4

Start heading levels at four within GitHub comments and descriptions in issues and pull requests (PRs).

In HTML:

<h4>This is a level 4 heading</h4>

In Markdown:

#### This is a level 4 heading

Accessibility implications

HTML headings should typically not skip levels. The page's primary content should have an H1, and the next level of headings should be H2. After H2, you can have H3, and so on.

GitHub issues and PRs use level 3 headings (<h3>), so if you want to use headings inside one, you should use a H4.

The correct heading level ensures a correct document flow and increases accessibility for screen reader users.

Screen reader implications

Screen readers provide several ways of document navigation, including navigation by heading. If the heading levels are incorrect, it's hard to determine which content belongs together.

For example, if you use an H2 in a GitHub comment, it may not be immediately apparent that the underlying content belongs to the previous comment.

To expand on the previous example, GitHub uses H2 for the "Navigation Menu," "Comments," and "Footer" sections. Putting an H2 in a comment would suggest a new major section of the page after the "Comments" section.

Wrap-up

Use the correct heading level inside descriptions and comments to ensure a logical document flow and improved screen reader accessibility.

In the current state of GitHub, this means using H4 in comments and descriptions for issues and PRs.

H4 is <h4> in HTML, and #### in Markdown.

Tip: Want to see these headings for yourself? Use the Table of Contents bookmarklet.