KB User's Guide - Advanced HTML - Formatting Nested Lists

Examples

When writing documentation, it is common to nest a sub-list inside of another list. This may be a list nested inside of another list of the same type, e.g. an unordered list nested in an unordered list:

• Pies
• Candy
• Cookies
  • Chocolate Chip
  • Oatmeal Raisin
  • Peanut Butter
• Cake

...Or a list nested inside a list of a different type, e.g. an unordered list nested inside an ordered list:

1. Mix dry ingredients and set aside.
2. Cream butter and sugar, then beat in egg.
3. Slowly blend in dry ingredients
4. Stir in one of more of the following mix-ins:
   • Chocolate chips
   • Nuts
   • Raisins/dried cranberries
5. Roll dough into balls and place on a cookie sheet.
6. Bake at 350°F for 8-10 minutes.

HTML Syntax

Do This

You want to think about the nested list as being a part of the parent list item, which means that that parent list item should not be closed until after the nested list has closed. Using the example above, the proper formatting is as follows:

<ul>
  <li>Item 1</li>
  <li>Item 2
    <ul>
      <li>Item 2.1</li>
      <li>Item 2.2</li>
      <li>Item 2.3</li>
    </ul>
  </li>
  <li>Item 3</li>
</ul>

As you can see, the closing </li> tag for Item 2 (the parent of the nested list) is closed after the nested list is closed (with a </ul> tag), and before the next list item on the same level begins.

Don't Do This

Below is an example of the most common way of incorrectly formatting a nested list. Here, the main issue is that list item 2 is closed (see the red tag) before the nested list is started. While browsers will generally display a list like this correctly, it will frequently cause problems if you are styling your list with CSS.

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
    <ul>
      <li>Item 2.1</li>
      <li>Item 2.2</li>
      <li>Item 2.3</li>
    </ul>
  <li>Item 3</li>
</ul>

Tips for Working with Multiple List Levels

Maintaining the correct formatting can be challenging, especially if you are working on a long list with several levels of nesting, e.g.:

• Item 1
• Item 2
  • Item 2.1
  • Item 2.2
• Item 3
  • Item 3.1
  • Item 3.2
    • Item 3.2.1
    • Item 3.2.2
  • Item 3.3
• Item 4
• Item 5

In this scenario, the best practice is to indent your HTML based on the list level. Doing this makes it much easier to see which items exist at the same level, and where you may be missing tags. In HTML, whitespace that exists outside of tags has no effect on the display of content, which means you can use this from a purely organization standpoint.

For the above list, you would want to have every <ul> and/or <ol> tag, as well as most <li> tags, on their own line. Additionally, it is extremely helpful to add spaces (two spaces is typically sufficient) as indentation every time you go one level deeper, e.g.:

<ul>
  <li>Item 1</li>
  <li>Item 2
    <ul>
      <li>Item 2.1</li>
      <li>Item 2.2</li>
    </ul>
  </li>
  <li>Item 3
    <ul>
      <li>Item 3.1</li>
      <li>Item 3.2
        <ul>
          <li>Item 3.2.1</li>
          <li>Item 3.2.2</li>
        </ul>
      </li>
      <li>Item 3.3</li>
    </ul>
  </li>
  <li>Item 4</li>
  <li>Item 5</li>
</ul>

This way, you not only get a visual depiction of the levels in your list, but you can also track through your HTML vertically to see if you are missing tags. For example, if you are entering two spaces as indentation, and you see a spot where there is a difference of four spaces between tags on adjacent lines, you will know that there is probably a missing tag that should be entered in between them.