Headings
Write headings in sentence case, with imperative verbs instead of gerunds, correct levels, and phrasing that works as a search query.
Use sentence case
Capitalize the first word and proper nouns only.
- Incorrect:
Configure Cache Policies - Correct:
Configure cache policies
Title case forces a capitalization decision on every word, and those decisions drift across pages. Sentence case removes the decisions, so headings stay consistent in both languages.
A product name keeps its capitals in any position, because it is a proper noun.
Lead with an imperative verb
A heading that names a task starts with the bare verb, never with a gerund.
- Incorrect:
Creating a bucket - Correct:
Create a bucket
Three reasons support the rule:
- Gerunds translate inconsistently as the first word of a heading. Google’s developer style guide bans them for that reason, and this documentation publishes every page in two languages.
- The heading lands in the same register as the steps under it, which Sentence structure defines as imperative. The reader scans one voice, not two.
Two -ing forms stay correct. A word in -ing that names a thing is a noun, so Getting started and Billing stay. A word in -ing later in the heading is also fine: Introduction to request logging.
Start the body at ##
The title field in the frontmatter renders as the page’s only H1. The body starts at ##, so a # heading in the body creates a second H1 and breaks the page outline.
Do not skip levels
Heading levels advance one step at a time: ### under ##, and #### under ###. A jump from ## to #### implies a level that does not exist, and readers and tools lose the structure.
Name the thing, not the section
A heading labels the content, not its position on the page. Limits says what the section holds. Step 1 says only where the section sits, and it says nothing when the section appears alone.
| Incorrect | Correct |
|---|---|
Step 1 | Create a bucket |
Some important limits to keep in mind | Limits |
Write headings that work as search queries
A retrieval system returns one section of a page, not the whole page. The heading tells the system and the reader what the section answers. Configure cache TTL retrieves, because it matches what a person with that task types. Configuration matches almost anything, so it retrieves nothing in particular.
- Incorrect:
Configuration - Correct:
Configure cache TTL
Use an acronym in a heading only when the page expands it
A heading may carry a well-established acronym, as long as the first line below it spells the term out. Configure WAF rule sets is a valid heading when the paragraph under it writes Web Application Firewall (WAF).
Word choice holds the expansion rule for the rest of the page.
Write code in a heading as plain text
A heading carries no inline code. An error string, a command, or an identifier in a heading keeps its own spelling and casing and loses the backticks: 403 Forbidden on legitimate requests, not `403 Forbidden` on legitimate requests. Backticks render a bordered code chip with a copy control, which breaks the heading line and follows the heading into the table of contents. A heading is a label, not a thing to copy.
Two mechanics follow. A string that ends in a period loses it, because a heading carries no end punctuation. A bare <placeholder> in a heading is parsed as a tag and fails the build, so name what it stands for instead.
Keep emojis out of titles
No emojis in titles, headings, or sidebar labels. Emojis break search indexing, read poorly in screen readers, and render inconsistently across platforms.