Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

dchacke
Copy link
Contributor

@dchacke dchacke commented Aug 25, 2023

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
Copy link

jnicho02 commented Sep 26, 2023

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
Copy link
Contributor Author

dchacke commented Jan 23, 2024

Has anyone had a chance to review this PR?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants