Lists

List or table?

Tables and lists are both ways to present a set of similarly structured items. Sometimes it's not obvious when to choose one presentation over the other. To decide which presentation to use, see List or table?

Note: Don't use a list to show only one item; a single item isn't really a list. If you want to set a single item off from surrounding text, then use some other formatting.

Types of lists

Choose one of the following list styles. The following table includes common ways to present lists in our documentation:

Multiple paragraph list items

Any list item can contain more than one paragraph.

To create multiple paragraphs, use the p element rather than using the br element. (The HTML specification describes which uses of the br element are legitimate and which aren't.)

Example of a list item that contains more than one paragraph:

• This list item is a single paragraph.

• This list item contains multiple paragraphs.

  As you can see!

• This is another list item that's only one paragraph long.

Introductory sentences for lists

Introduce a list with the appropriate context. In most cases, precede a list with an introductory sentence. The sentence can end with a colon or a period; usually a colon if it immediately precedes the list, usually a period if there's more material (such as a note paragraph) between the introduction and the list.

If the list doesn't need any additional context other than the heading that immediately precedes the list, it's OK to not introduce a list with an introductory sentence.

Introduce a list with a complete sentence, not a partial one that's completed by the list items. You can also use the following as a noun phrase (see following in the word list).

For information about introducing sub-steps, see Sub-steps in numbered procedures.

For information about punctuation and capitalization of lists, see Capitalization and end punctuation.

Unusual list numbering

Use nonstandard numbering in the following situations:

• To present a list in reverse-numerical order, use an ol element with a reversed attribute.
• To set a value manually, use the value attribute. In some cases, setting a value manually can be convenient. However, in most cases, it isn't a good idea to manually number a list item in a numbered list, because if the number of items changes later, you'll have to manually change the value.

Sub-steps in a numbered procedure

For information about sub-steps in a numbered procedure, see Procedures.

Parallel syntax

Use the same syntax/structure for all list items in a given list, if possible.

Capitalization and end punctuation

Capitalization and end punctuation depend on the type of list and the contents of the list.

Numbered, lettered, and bulleted lists

Start each list item with a capital letter, unless case is an important part of the information conveyed by the list—such as in a list of glossary terms.

End each list item with a period or other appropriate sentence-ending punctuation, except in the following cases:

• If the item consists of a single word, don't add end punctuation.
• If the item doesn't include a verb, don't add end punctuation.
• If the item is entirely in code font, don't add end punctuation.
• If the item is entirely link text or a document title, don't add end punctuation.

Description lists

Sometimes it's useful to add an explanatory phrase to a list item, which can affect the punctuation. In general, don't add an explanatory phrase to only a single list item; instead, use a description list, and provide explanatory phrases for all items.

In most contexts, start each term (dt element) with a capital letter.

Don't end the term with a period. Do generally put a period at the end of each dd ("description") element.

Description lists that use run-in headings

In most contexts, format run-in headings as follows:

• Start the run-in heading with a capital letter.
• End the run-in heading with a period or a colon, but be consistent within the list.
• You can decide whether to bold the punctuation that ends the heading based on factors such as on-page consistency.

For the descriptions that follow the punctuation, capitalize the first letter as follows:

• If the text follows a period, start the text with a capital letter.
• If the text follows a colon, start the text with a lowercase letter.

To end the descriptive text, punctuate as follows:

• If the description follows a period, end the description with a period.
• If the description follows a colon, do one of the following:
• If the description is a list of items or short phrases without verbs, don't include a period.
• If the description includes a verb or expresses a standalone thought, end the description with a period.

Don't use a dash to set off a description from an item in a description list. For more information, see Colons instead of dashes in lists.