Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Headings

    March 9, 2025
    + 12

    Use headings to split up the content on a page and make it easier for a user to scan. A heading indicates what information a user finds in a specific section of the page.

    This guidance applies only to H<n> elements. For guidance on captions for images and tables, see Images and Tables, respectively.

    Use the following guidance to write headings in your topics:

    Capitalization

    Use title case for all headings. Couchbase uses the Chicago Manual of Style for its heading capitalization. Vale flags any headings that don’t match the following criteria:

    • Always capitalize the first word.

    • Capitalize the main nouns, verbs, and adjectives.

    • Leave articles, coordinating conjunctions, prepositions and other connecting words in lowercase, such as and, the, and to.

    Length

    Try to keep headings as short and to-the-point as possible. Try to fit your heading in a single line.

    Frequency

    Use a heading whenever it makes sense to do so. Add a heading when you’re starting a new thought or need to highlight something new and important to the user. Keep headings useful, and make sure that you always have content in between two headings. Vale flags any headings that appear directly on top of each other with no content in between.

    Depth

    Don’t go past an H4 heading. You don’t need to have more than 4 levels of headings in your text.

    Don’t add Parentheses to headings.

    The content of your H1 heading also needs to match the type of topic you’re writing:

    Content Type Heading Style Examples

    Concept topic

    Concept headings are a single noun, which accurately outlines the concept you’re describing. Use additional words if you feel that a single noun can’t accurately describe the content of the page.

    Clusters

    Indexes

    How-to or Tutorial topic

    Task headings are short imperative phrases that start with a verb that does something to a noun.

    Delete a Cluster

    Create an Index

    Explore Your Data

    Reference topic

    Reference headings are short phrases that state what kind of reference content the user finds on a page.

    Audit Events

    Error Messages

    Rebalance Reports

    Format headings using an equals sign (=). The number of equals signs corresponds to the heading depth that Antora renders. For more information, see Standard Document Structure in the Contributing to the Documentation guide.