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:

Resulting text:
 * first-level bulleted list item
 * second-level unbulleted list item
 * 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:

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:

Unsemantic nesting:

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

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

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 ).

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:

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:

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:

Resulting text:
 * first-level bulleted list item continue first-level list item
 * another first-level bulleted list item