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.
- 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, and other full-length works. 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.
- Do not use italics for emphasis in HTML. Instead, use
<em>. For Markdown, you can still use
_because Markdown doesn't allow semantic tagging.
- Do not underline.
- Code font
- Use semantic HTML and use code font,
`, 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 most things that have anything to do with code, such as class names, method names, HTTP status codes, 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, put titles in quotation marks, unless it's 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.