The page summarizes, and provides a quick reference for, many of the general text-formatting conventions covered elsewhere in the style guide.
- Use bold formatting,
**, 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.
- Use italics formatting,
_, when drawing attention to a specific word or phrase, such as when defining terms or using words as words.
- 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
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 emphasis in HTML, use the
<em>element, which renders as italics in most contexts. To indicate emphasis in Markdown, use underscores (
_) or single asterisks (
*); you can't do semantic tagging in Markdown.
- Do not underline.
- Code font
<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,
```, 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 placeholder variables.
- Sentence case and capitalization
- Use American English style for general capitalization. Use sentence case in all headings, titles, and navigation.
- 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,
`, 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.