Skip to content

No Faux Headers In Lists ​

Don't use bold label + dash + description as a fake header inside a bullet list.

Why ​

A real header gives navigation for free: a table of contents, an anchor and search.

How To Apply ​

  • Short, scannable items: a flat dash list is correct.
  • An item that is a heading-and-body pair (a label plus a sentence or more explaining it) becomes a ### Label header with the body below as a paragraph.
  • The test while drafting: if trimming an item's description would lose meaning, the item wants a header.