LLM Best Practices

Headlines and Subheads

3 min read

View markdown source

Overview

A headline does three jobs at once: it tells a human what the piece is, it signals to a search index what query it answers, and it tells an LLM agent whether the page is worth fetching. The same patterns serve all three. This page covers headlines (the H1) and subheads (H2 and H3).

Headline patterns that work

Three reliable shapes. Pick the one that matches the artifact.

  • Noun phrase + suffix: “Astro: Best Practices.” Works for reference pages.
  • Direct question: “When should you use SQLite?” Works for decision pieces.
  • Claim or rule: “Lead with the rule, not the rationale.” Works for opinion or essay.

Avoid clever or oblique headlines on reference content. The headline is the routing hint; clever costs comprehension.

Length and shape

  • 40 to 70 characters for the H1. Below 40 reads sparse; above 70 truncates in search results and OG cards.
  • One H1 per page. Quartz renders it from title.
  • The H1 should match the page title in frontmatter exactly. Mismatches confuse agents that index by either.

Verbs in subheads

Subheads (H2) open with the rule, which usually means a verb. See voice for the broader rule.

  • “Lead with the rule.” Verb-first.
  • “Avoid em-dashes.” Verb-first.
  • “Length and shape.” Noun phrase, used only when the section is a property list, not a rule.

Mix sparingly. A page of 100% verb-first subheads reads as a script; a page of 100% noun-phrase subheads reads as a glossary.

Keywords

Put the keyword in the H1 and one H2. Do not stuff.

  • “Tailwind v4: Best Practices” is enough. “Tailwind v4 Best Practices for Modern Web Development” is not.
  • The H2 that owns the keyword can be more verbose: “When to use Tailwind v4.”
  • After H2, optimize for clarity over keywords.

Subhead-to-content match

Every subhead is a promise. The first paragraph under it must pay off.

  • If the H2 is “Avoid em-dashes,” the first sentence should restate the rule and explain it.
  • If the H2 is “Length and shape,” the first sentence should name the lengths or shapes.

Mismatch is a tell: the writer added a header to organize their thoughts and never came back to align the section.

Sentence case, always

Sentence case for every level of heading. Quartz applies styling; you do not need title case for visual weight.

  • Yes: “Headlines and subheads.”
  • No: “Headlines And Subheads.”

Proper nouns stay capitalized: “Tailwind v4: Best Practices.”

Subhead density

One H2 every 80 to 200 words of body is healthy.

  • Two H2s back to back with no body between them is a smell; the headers are doing the writing’s work.
  • One H2 owning 600 words of body should split. See articles.

Page titles for LLM routing

The H1 plus summary in frontmatter is the routing hint for agents. Together they should let a model decide, in two seconds, whether to fetch the body.

  • H1: what the page is.
  • Summary: what rule or decision the page resolves.
  • Together, they answer “should I open this?”

Graph View

Backlinks