Unobtrusively support the breaking up of ordered lists without resetting their indices/steps

[dchacke]

Markdown is known for resetting the counter on broken-up ordered lists, where this...

1. Foo
2. Bar

Some interruption here

3. Baz

...turns into...

1. Foo
2. Bar

Some interruption here

1. Baz

This behavior can be frustrating since markdown blatantly disregards the 3 the user typed and implicitly turns in into a 1. Various hacks have been suggested, but none of them are exactly satisfying.

This PR fixes the issue by associating each li in an ordered list with an explicit data-step attribute that is based on the number the user typed:

<ol>
  <li data-step="1">Foo</li>
  <li data-step="2">Bar</li>
</ol>

<p>Some interruption here</p>

<ol>
  <li data-step="3">Baz</li>
</ol>

This change is probably backwards compatible for consumers since it is unlikely that they depend on a data-step attribute on li elements already. Nor do data attributes change UIs in any way unless configured to do so – they are generally unobtrusive.

If consumers do depend on pre-existing data-step attributes, it's easy to disable the data-step attribute on the producer side by simply not including it:

def list_item contents, list_type, step = nil
  "<li>#{contents}</li>"
end

Consumers can opt in to the new behavior with this simple CSS:

li[data-step]::marker {
  content: attr(data-step) '. ';
}

If they do not, counters will continue to break as before.

However, on the producer side, those who override the list_item method will need to add a step parameter to support the new 3-arity, as shown above:

def list_item text, list_type, step = nil
  # ...
end

Therefore, this PR introduces a breaking change – hence the new major version 7.

For unordered lists, the step parameter can simply be disregarded by producers (though it is still passed to list_item but should always be 0). It does not make it to the consumer, ie no li elements in unordered lists ever have any data-step attribute.

I have no experience writing C and took a bunch of educated guesses with the help of AI. Please take a close look at the proposed changes. I did add tests and they all pass for me; I've also tested the behavior on a site for which I use the gem and it seems to work fine.

If this PR isn't satisfactory, an alternative implementation to consider is to add a start attribute to the ol based on the first list item's number. Something like...

5. Foo
6. Bar

...turning into:

<ol start="5">
  <li>Foo</li>
  <li>Bar</li>
</ol>

I see that's how GitHub does it. However, I believe this approach would make turning HTML back into markdown more difficult. In addition, the consumer-side wouldn't be backwards compatible, nor would this approach allow arbitrary, eg non-subsequent, counters.

EDIT 2023-08-26: Made some edits throughout.

[jnicho02]

My first reaction was that

<ol start="50">

is the 'official' html....but I see that data-step is being used in a number of places for progress icons, etc. Has it become 'official' anywhere? I actually prefer the extra control that it gives and hope that this PR gets accepted soon.

[dchacke]

Has anyone had a chance to review this PR?