Formatting content

Headings and subheadings

Headings and subheadings are written in sentence case. 
Organize headings and subheadings hierarchically, with headings first (H1), following by subheadings (H2, H3). 

  • Page and article titles use a H1 level heading
  • Specific sections and subsections use subheadings (H2, H3) and make the content more scannable.

Here’s a good example.


Lists with titles

In situations when we list a series of options we should format the text like this:

Title: description

Numbered lists

When are we using these lists?

Only use ordered lists for step-by-step instructions. Separate steps into logical chunks, with no more than two related actions per step. When additional explanation or a screenshot is necessary, use a line break inside the list item.


Quotation marks

Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.

Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.

Don’t add an extra emphasis (italic or bold) to quotes.


Use the en dash ( option + – ) without spacing to indicate a range of values; for example, May 10th–15th.

Use the em dash ( option + shift + – ) without spacing in running text or for showing attribution of a quote.

Never use double hyphens (–) to represent a proper dash.


Ellipses (…) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama (?), and don’t use them in titles or headers.

“Where did all those donuts go?” Christy asked. Lain said, “I don’t know…”

Ellipses, in brackets, can also be used to show that you’re omitting words in a quote.

“When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, […] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”


Spell out the numbers one through nine and use numerals for the numbers 10 and above.

Interface elements


Use bold when citing an example of an interface element, or referencing button and navigation labels in step-by-step instructions:

  • When you’re all done, click Install.
  • In the Appearance menu, choose Save.

Use italics to indicate the title of a long work (like a book, movie, or album) or to emphasize a word. Example: George really loves Pixelgrade Upstairs.

Don’t use any combination of italic, bold, caps, and underline.


Use the “→” symbol to represent navigation through sections.

Example: Navigate to Appearance → CustomizeMenus and choose a menu, then click on a menu item that you want to transform into a button;