emphasis-001 should GuidesAPI docsMarketingBlog Italicize mathematical variables in text.
Emphasis
These rules cover italics and bold as emphasis, introducing new terms, formatting math variables and titles of works, and the semantic HTML behind them. Bolding UI element names is covered under UI elements, and code font is covered under inline code.
Italicize math variables
Section titled “Italicize math variables”Examples
- ✓ If n exceeds the page size, the response is truncated.
- ✗ If n exceeds the page size, the response is truncated.
Rationale
Italic is the math convention for a variable, distinguishing it from surrounding text.
Italicize new terms at first use
Section titled “Italicize new terms at first use”emphasis-002 should GuidesAPI docsMarketingBlog Italicize the first mention of a new term when it is immediately defined.
Examples
- ✓ A webhook is an HTTP callback that fires when an event occurs.
- ✗ A webhook is an HTTP callback that fires when an event occurs.
Rationale
Italic on a term’s first, defining use signals that it is being introduced.
Avoid footnotes
Section titled “Avoid footnotes”emphasis-003 should GuidesAPI docsMarketingBlog Avoid footnotes; prefer cross-references, inline notes, or parentheticals instead.
Examples
- ✓ Rate limits vary by plan. For details, see Quotas and limits.
- ✗ Rate limits vary by plan.[^1]
Rationale
Footnotes pull the reader away from the flow, so an inline note or cross-reference keeps the information in place.
Semantic emphasis tags
Section titled “Semantic emphasis tags”emphasis-004 should GuidesAPI docsMarketingBlog Distinguish em (semantic emphasis) from i (non-emphasis italics) and strong (semantic importance) from b (non-semantic bold) in HTML.
Examples
- ✓ You must
<em>never</em>commit an API key to source control. - ✗ You must
<i>never</i>commit an API key to source control.
Rationale
The semantic tags carry meaning to assistive tech that the presentational tags do not.
Pull quotes in editorial content
Section titled “Pull quotes in editorial content”emphasis-005 should MarketingBlog Use pull quotes sparingly in editorial content: one or two per article at most, kept to a sentence or two. Self-quotes lifted from the article’s own text need no attribution; person-quotes from external sources are always attributed. Don’t use pull quotes in reference documentation.
Rationale
Pull quotes are a narrative device that suits editorial writing but interrupts scanning in reference documentation, so they belong on the marketing site and blog and stay out of the docs.
Titles of published works
Section titled “Titles of published works”emphasis-006 should GuidesAPI docsMarketingBlog When referencing books, films, articles, papers, blog posts, games, or other named works, preserve the original capitalization of the title as published. Italicize titles of full-length works, use straight double quotation marks around titles of shorter works, and use the canonical identifier for RFCs, specifications, and standards documents (RFC 7234, ISO 8601, WCAG 2.1).
Examples
- ✓ The examples follow The C Programming Language.
- ✗ The examples follow “The C Programming Language.”
- ✓ Timestamps follow RFC 3339.
- ✗ Timestamps follow the Internet Timestamp Format spec.
Rationale
A title belongs to its author and publisher, so preserving the original capitalization gives the reader accurate information and makes the work easier to find.