Avoid heading tags in Handbook pages

Do not use <h1>, <h2>, <h3>, <h4>, <h5>, and <h6> heading tags. Use of these tags inside of a book page is a sign of a structural problem. They should never appear. The presence of these elements implies:

  • It will be impossible for others to add or re-arrange sections unless they have edit permissions for a page.
  • Individual authors can hijack the apparent (presentational) structure of a book by arbitrarily beginning new chapters, for example
  • There is no guarantee of coherence (hierarchy) in the presentation of the book
  • The structure of the document is not accessible to the navigational elements presented by Drupal - sections will disappear from the book navigation view, forward/up/next links, etc.

If you feel the urge to include them in your book page, one or more of the following is probably true:

  • Your page is too long. If readers need to scroll through a long page, they will probably need the navigational clues that headings provide - but they will in all cases be better served by having the page divided into true subsections via child nodes.
  • You are trying to present some kind of list. Try using <dl>, <dt>, <dd> instead.
  • You are trying to achieve visual impact. Visual impact is OK, though it's often not done well. If you must, do it with style (pun intended).
  • Your page is essentially just a container for subsections - try pushing content up into the parent or down into children and eliminate the page entirely.
 
 

Drupal is a registered trademark of Dries Buytaert.