Start Building for Free


9 months 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.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.