Ctrl.blog

Need to insert a figure, paragraph, or illustration in the middle of an organized list but don’t want to restart the ordinal counter? Totally doable.

I’ve noticed the most common ways of re-numbering ordered lists is either by embedding a paragraph inside a regular list item, or by manually numbering and breaking up list items inside paragraphs. More creative writers set list-type: none; in CSS and number their lists manually.

Here are some bad examples of the common approaches for re-ordering numbered list in HTML:

<ol>
  <li>One</li>
  <li>Two
    <p>Paragraph</p></li>
  <li>Three</li>
</ol>

<p>1. Yaski<br/>
   2. Kaksi</p>
<p>Paragraph</p>
<p>3. Kolme</p>

The above approaches work, but the markup gets ugly and you lose some list semantics about the order of the content. The embedded paragraph also inherits the list’s left padding which will often be quite big and undesirable. When you start embedding figures, tables, or multiple paragraphs you’re getting into trouble with those approaches.

What you can do instead is to set the start attribute on a second <ol> element to offset the counter. This allows you to add a lengthy example or figure into a list and continue with the list below it like nothing happened.

<ol>
  <li>One</li>
  <li>Two</li>
</ol>
<p>Paragraph</p>
<ol start="3">
  <li>Three</li>
</ol>

This can be especially useful for tutorial and how to texts. These texts in print will often break-up a list to show output or discuss a set of instructions in greater detail, before continuing on the ordered list of instructions below the explanation.

On the web, however, most authors don’t seem to know how to offset the ordered list counters and either apply variations of the workarounds shown at the top of this article, or completely alter the natural flow and structure of their texts to fit a flow where the ordered list counters are reset every so often. Splitting their texts into smaller chunks and applying liberal uses of sub-headlines is a popular way of masking these kinds of rewrites.

The start attribute is well understood by screen-readers and text-to-voice systems. Some versions of WebKit (Safari), however, will be a bit over-eager and will read the list numbering prefixed again before every sentence when using a start attribute.

For example, <ol start="2"><li>A. B. C.<li></ol> may be read as “Two: A. Two: B. Two: C.” instead of the expected “Two: A. B. C.” This can also happen to lists where items span more than one-line of text even without a start attribute so it’s not a unique problem. If the <ol> element only contains one <li> element, you can set the value attribute on the <li> element to the <li>’s desired ordinal value. Many of the screen readers I’ve tested didn’t understand this even though all browsers displayed it correctly.

You’re out of luck if you’re trying to achieve this in a lightweight formatting language like Markdown. This is simply not supported. In most Markdown implementations you can still include a block of HTML that can be used instead of a Markdown-formatted list.

Have a look at Using CSS counters if you’re interested in other ways of manipulating document counters. Especially for use with section headlines!