Audit Heading Levels in a Markdown Guide
Admin ·
Before publishing a Markdown guide, check whether the heading order gives readers a usable outline. Compare the actual parsed headings with your intended section levels, especially in a document that includes Markdown examples.
Markdown Heading Structure Auditor
Locate three findings in the release guide
Select Load example and Audit headings. The outline lists five headings. On line 3, Install moves from H1 to H3. On line 13, Verify repeats the title from line 5. On line 15, the H2 is empty.
Edit line 3 to use two hashes, give the later Verify heading a more specific title, and add a title to the empty H2. Run the audit again. The five headings remain and the three findings clear.
CommonMark 0.31.2, ATX and Setext heading rulesW3C WAI guidance on heading ranks
Include a quoted heading when it belongs in the review
Return to the example and enable Include headings in quotes and lists. Audit again. Quoted sample appears as a nested H2 on line 7 and the outline now has six entries. The line beginning with # inside the code fence still stays out of the outline.
An underline made from equals signs or hyphens can create a Setext heading. Add a blank line and try a paragraph followed immediately by an equals-sign underline. The auditor uses the first content line for its location.
Compare the saved report with the published outline
The report records heading levels and source positions. Reopen the text download and compare the referenced lines with your editor. Review the outline on the resulting page as well, especially if a template supplies the page title.
The duplicate check uses displayed text, so emphasis markers or capital letters alone may leave two headings with the same title for readers. Keep duplicated titles when navigation still makes sense or make each heading more descriptive.
CommonMark 0.31.2, ATX and Setext heading rulesW3C WAI guidance on heading ranks
Common questions
Why can several sections go back to H2?
Returning to a higher level begins a sibling or parent section. The skipped-level finding concerns jumping deeper by more than one level.
Can this report certify the accessibility of a page?
The report covers source heading structure. Review the rendered page, navigation and assistive technology behavior to assess accessibility.
Sources
Put it into practice.
- Markdown Heading Structure Auditor
- Markdown Validator
- Markdown to HTML Converter
- Markdown to Slack and Teams
Related guides
- Check Markdown Source Before Publishing
- Convert Markdown release notes to HTML
- Draft a Markdown Update for Slack or Teams
- Trace Markup Accessibility Issues to Source
- Export Markdown Metadata and Heading Lines
- Trace Missing Markdown Anchors and References
- Edit a Rain Barrel Article Outline
- Find an Overflow Hose Heading Gap