The page summarizes, and provides a quick reference for, many of the general text-formatting conventions covered elsewhere in the style guide. For more information, see Visual formatting.
- Bold
- Use bold formatting,
<b>
or**
, for UI elements and at the beginning of notices. - Although a double underscore,
__
, can also indicate bold styling in Markdown, it can be difficult to distinguish in a text editor. It's best to use the double asterisk for bold in Markdown. - Italic
- Use italics formatting,
<i>
or_
, when drawing attention to a specific word or phrase, such as when defining terms or using words as words. - Although an asterisk,
*
, can also indicate italics in Markdown, we recommend underscores to make it easier for humans to distinguish italics from bold in the Markdown file. - Italicize titles of books, movies, web series, and other full-length works, unless they're part of a link. For more information, see cross-references.
- Italicize parameter names. For example, when you refer to the parameters of a method like
doSomething(Uri data, int count)
, italicize data and count. - Italicize mathematical variables and version variables. For example, x + y = 3, version 1.4.x.
- To indicate semantic emphasis in HTML, use the
<em>
element, which renders as italics in most contexts. To indicate emphasis in Markdown, use underscores (_
), which render as italics; you can't do semantic tagging in Markdown. - Underline
- Do not underline.
- Code font
- Use
<code>
in HTML or`
in Markdown to apply a monospace font and other styling to code in text, inline code, and user input. - Use code blocks,
<pre>
or```
, for code samples or other blocks of code. - Do not override or modify font styles inline.
- Use code font to mark up code, such as class names, method names, HTTP status codes, console output, and placeholders.
- Capitalization
- Use American English style for general capitalization.
- Use sentence case in all headings, titles, and navigation.
- Use all-capitals for placeholders.
- Quotation marks
- In general, use American English style when punctuating quotations.
- For titles of shorter works—such as articles or episodes in a web series—put titles in quotation marks, unless they're part of a link.
- Font type, size, and color
- Do not override global styles for font type, size, or color.
- Use semantic HTML to
control the style of text on a page. For example, use code tags,
<code>
or`
, instead of manually styling text with a monospace font. - Other punctuation conventions
- Don't use ampersands (&) as conjunctions or shorthand for and. Use and instead. That includes headings and navigation. Exception: It's okay to use & in cases where you need to refer to a UI element or the name of a menu that uses &.
- Put quotation marks and end punctuation outside of link text.