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? in the page about tables.

Types of lists

Here are some common ways to present lists in our documentation:

List type Used for HTML elements
Numbered list Sequence of steps to be performed in order. Note that nested sequential lists are labeled with lowercase letters or lowercase Roman numerals. ol, li
Lettered list (upper case) Options to choose among, especially mutually exclusive options. ol class="upper-alpha", li
Bulleted list Set of items that's neither a sequence nor options. ul, li
Description list Set of terms, each with a description, definition, or explanation. dl, dt, dd

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.

Examples of the different kinds of lists

Here's a sequence of steps to follow:

  1. Open the box.
  2. Remove the bobcat from the box.
  3. Feed the bobcat.

Here's a set of options for which programming language to use:

  1. Java.
  2. JavaScript.
  3. Go.
  4. Dart.

Here's a list of things that can go wrong, in no particular order:

  • Your bicycle might explode.
  • The sun might go out.
  • An ant might break its leg and require a tiny splint.

Here's a list of things to do after breakfast, in order:

  1. Go shopping.
    1. Buy groceries.
      • Flour.
      • Eggs.
      • Sugar.
      • Butter.
    2. Go to mall.
      1. Buy dress.
      2. Buy shoes.
  2. Make cake.
  3. Build birthday present out of spare parts.
  4. Clean house.

See also Sub-steps in numbered procedures.

Here are some descriptions of types of birds:

Emu
The best kind of bird.
Crow
The other best kind of bird.
Peacock
Also the best kind of bird.
Phoenix
An even better kind of bird.

Multi-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 <br> are legitimate and which aren't.)

Examples of multiple paragraphs within one item

Example of a list item containing 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

In most cases, you should 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.

Always introduce a list with a complete sentence, not a partial one that's completed by the list items.

For information about punctuation and capitalization of lists, see Punctuation and capitalization.

Examples of introductory sentences

Not recommended:

Use the Submit button to:

  • submit the form
  • indicate that you're done
  • allow the next person to enter their data

Recommended:

Use the Submit button for any of the following purposes:

  • To submit the form.
  • To indicate that you're done.
  • To allow the next person to enter their data.

Not recommended:

To get the USB driver:

  1. Click Tools > Android > SDK Manager.
  2. Select Google USB Driver and then click OK.

Recommended:

To get the USB driver, follow these steps:

  1. Click Tools > Android > SDK Manager.
  2. Select Google USB Driver and then click OK.

Unusual list numbering

A couple of situations involving nonstandard numbering:

  • To present a list in reverse-numerical order, use <ol reversed>.
  • 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. But in some cases, setting a value by hand can come in handy. To set a value manually, use the value attribute.

Sub-steps in a numbered procedure

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

Parallel syntax

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

Punctuation and capitalization

In numbered, lettered, and bulleted lists, in most contexts, start each list item with a capital letter and end each list item with a period.

Exception: If a list item consists entirely of a literal string (such as a keyword), don't capitalize it or put a period after it.

In description lists, in most contexts, start each term with a capital letter, but don't end the term with a period. In other words, for the dt ("term") elements of a description list, leave off the period at the end of each item. Do generally put periods at the ends of the dd ("description") elements.

发送以下问题的反馈:

此网页
Google Developer Documentation Style Guide
Google Developer Documentation Style Guide