User:Isaacl/On wikitext list markup

Basic description

Adding a *, #, or : character at the beginning of a line starts a new list of a specific type—bulleted, numbered, or unbulleted—as well as a specific item in that list. (Technically, it's more complicated than that for unbulleted lists, but I'll ignore that for this description.) So a string of these characters defines a nesting of lists. For example, *:# means (reading from right to left) a third-level numbered list item nested in a second-level unbulleted list item nested in a first-level bulleted item.

Wikitext:

* first-level bulleted list item
*: second-level unbulleted list item
*:# third-level numbered list item

Resulting text:

• first-level bulleted list item

  second-level unbulleted list item

  1. third-level numbered list item

To keep the result tidy for screen readers and the Visual diff viewer, it's best to avoid changing the nesting of lists in the middle. So if responding below a comment that starts with **:, if you want to preserve the same indent level, this corresponds to adding another item of the same type as the current list, and so you should use **:. If you want to add an additional indent level, then you should copy the current prefix, and add the character corresponding to the new type of list you want to have. So with this example you could use **::, **:*, or **:#, depending if you wanted to add a fourth-level unbulleted, bulleted, or numbered item.

Example: replying to a third-level item with an unbulleted comment

Wikitext:

* first-level comment
** second-level reply
**: third-level reply
**:: fourth-level reply: copy third-level prefix and add :

Resulting text:

• first-level comment
  • second-level reply

    third-level reply

    fourth-level reply: copy third-level prefix and add :

Screen readers

To expand on the issues with screen readers: if you switch from, say *** to :::*, as many people do, then this closes the three levels of bulleted lists, and starts four lists, all nested within each other. The screen reader will describe the end of the first three bulleted lists and the opening of the next four. This introduces a lot of extraneous noise when trying to follow the threads of conversation.

Recommended practice:

* first-level item
** second-level item
*** third-level item
**** fourth-level item

<ul><li>first-level item
<ul><li>second-level item
<ul><li>third-level item
<ul><li>fourth-level item</li></ul></li></ul></li></ul></li></ul>

Unsemantic nesting:

* first-level item
** second-level item
*** third-level item
:::* fourth-level item

<ul><li>first-level item
<ul><li>second-level item
<ul><li>third-level item</li></ul></li></ul></li></ul>
<dl><dd><dl><dd><dl><dd><ul><li>fourth-level item</li></ul></dd></dl></dd></dl></dd></dl>

Visual diff viewer

Regarding the Visual diff viewer: consider a list as follows, and the generated HTML:

* Comment one
* Comment two
* Comment three

<ul><li>Comment one</li>
<li>Comment two</li>
<li>Comment three</li></ul>

If someone adds a reply to comment one but changes the list type, like so:

* Comment one
:* Reply one
* Comment two
* Comment three

<ul><li>Comment one</li></ul>
<dl><dd><ul><li>Reply one</li></ul></dd></dl>
<ul><li>Comment two</li>
<li>Comment three</li></ul>

The added wikitext turns one bulleted list into three lists (with the new unbulleted list having a bulleted sublist). The Visual diff viewer treats this as if Comment two and Comment three were deleted and then re-added as a new list. The resulting visual diff output thus highlights pseudo-changes that weren't actually made. Compare this to the visual diff output with a properly nested reply.

Definition lists

Technically, a : list item should be preceded by a ; list item. The semi-colon specifies a "definition term", and the colon specifies a "definition description". Semantically, these should only be used for definition lists, such as a glossary. However for historical reasons, lists of colon-only items are used by editors to create unbulleted list items in discussion threads. In articles, templates such as {{unbulleted list}} or {{plainlist}} should be used (see Wikipedia:Manual of Style/Lists § Unbulleted lists).

In rare instances, some editors use a semi-colon item to visually resemble a heading that doesn't appear in the table of contents. This should not be used in articles as it provides the wrong semantics for screen readers and anything else interpreting the meaning of the markup.

Sample markup

Examples of markup for some scenarios that aren't supported by the basic wikitext list syntax:

New paragraph within a list item

Use the {{pb}} template to insert a paragraph break. Since newlines within a template invocation do not reset the list nesting levels, you can add newlines before the closing }} for legibility.

Wikitext:

* first-level bulleted list item
** second-level bulleted list item {{pb
}}new paragraph within second-level bulleted list item
** another second-level bulleted list item {{pb
}}another new paragraph within second-level bulleted list item
* another first-level bulleted list item

Resulting text:

• first-level bulleted list item
  • second-level bulleted list item
    new paragraph within second-level bulleted list item
  • another second-level bulleted list item
    another new paragraph within second-level bulleted list item
• another first-level bulleted list item

Continuing a list item after an embedded sublist

Without using a template, the appearance can be simulated:

Wikitext:

* first-level bulleted list item
** subitem 1
** subitem 2
*<li style="list-style:none;">(simulated) continue first-level list item</li>
* another first-level bulleted list item

Resulting text:

• first-level bulleted list item
  • subitem 1
  • subitem 2
• (simulated) continue first-level list item
• another first-level bulleted list item

Within an article, use the {{bulleted list}} template so the underlying HTML will reflect that the sublist is embedded within the list item:

Wikitext:

* first-level bulleted list item {{bulleted list
|1=subitem 1
|2=subitem 2
}} continue first-level list item
* another first-level bulleted list item

Resulting text:

• first-level bulleted list item
  • subitem 1
  • subitem 2
  continue first-level list item
• another first-level bulleted list item

Additional information

• Wikipedia:Manual of Style/Accessibility § Lists
• Help:Talk pages § Indentation