Start Building for Free


1+ year ago1 min read
  • Write headings in a logical sequence. If you read section titles in order, the flow should present a good storyline for the doc.

  • Do not skip heading levels. For example, try not to jump from h2 to h4, missing out h3.

  • Try not to have a heading with no paragraph text to accompany it. Add at least an overview or intro to what comes next.

  • All headings are in sentence case. This means only the first word and proper nouns are capitalized.

    • Good: CircleCI docs style guide

    • Bad: CircleCI Docs Style Guide

  • Jekyll automatically creates an h1 heading from the document title, so only use h2 and greater in the body of the doc.

  • Where possible, headings should begin with a verb.

    • Good: "Grooming cats"

    • Bad: "Cats"

  • When referencing headings in prose, use the full heading with no quotes, and use title case.

Suggest an edit to this page

Make a contribution
Learn how to contribute