Skip to content

Add Vale test for maximum heading depth

Russell Dickenson requested to merge russell/vale-add-max-heading-depth-test into master

What does this MR do and why?

What

Adds a new Vale test which flags as a warning any Markdown heading at a depth of 4 or greater.

Why

  • Headings at a depth greater than 3 suggests that the page is too complex, contains too many headings, or both.
  • The per-docs page navigation pane cannot display any sections at heading level greater than 5.

Note: The style guideline tested by this Vale rule is documented at https://docs.gitlab.com/ee/development/documentation/styleguide/#headings-in-markdown.

Related merge request

Related to Note maximum Markdown heading depth for docs (!93783 - merged) where new instructions were added to the style guide.

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Russell Dickenson

Merge request reports