Issue with "counter-reset": the example is a bit confusing

[MatsPalmgren]

MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/counter-reset

What information was incorrect, unhelpful, or incomplete?

The example at the start of the article is a bit confusing.
See https://bugzilla.mozilla.org/show_bug.cgi?id=1717772 for details why.
The example kind of misleading since it's not how you would typically use nested counter scopes.
(I guess it was written before we changed CSS counters to be compatible with HTML list ordinals, which are now defined in terms of the built-in CSS list-item counter.)

Specific section or headline?

What did you expect to see?

Did you test this? If so, how?

MDN Content page report details

• Folder: en-us/web/css/counter-reset
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/counter-reset
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/counter-reset/index.html
• Last commit: mdn/content@8bc3398
• Document last modified: 2021-06-17T02:43:53.000Z

[rachelandrew]

Thanks for raising this, and for the test cases. I've updated the example to use counters(). Once that shows up on the page I'll go add some text to explain what is happening there.

[MatsPalmgren]

I think the main issue with the example is that it's poorly marked up. One should never have first and second level headings be siblings in a flat list like this. I'm aware that it's just a brief example just to show the effect of a few counter-reset values, but people take these examples and use them as templates for their documents. So it would be great if we could flesh out the example with markup as recommended by the HTML spec. I believe that would look something like this:

<style>
#default-example {
    counter-reset: chapter-count;
}
h2, h3 {
    counter-increment: chapter-count;
}
h2::before, h3::before {
    content: "Chapter " counters(chapter-count, ".") ": ";
}
</style>

<section id="default-example" class="default-example">
  <h1>Alice's Adventures in Wonderland</h1>
  <section>
    <h2>Down the Rabbit-Hole</h2>
    <p>Alice was beginning to get very tired ...</p>
    <section>
      <h3 id="example-element">The Pool of Tears</h3>
      <p>`Curiouser and curiouser!' cried Alice ...</p>
    </section>
  </section>
  <section>
    <h2>A Caucus-Race and a Long Tale</h2>
    <p>They were indeed a queer-looking party ...</p>
  </section>
  <section>
    <h2>The Rabbit Sends in a Little Bill</h2>
    <p>It was the White Rabbit ...</p>
  </section>
</section>

In particular, each level should be wrapped in nested sectioning elements (<section> here).
Then the example renders as intended also in Chrome.

[hamishwillee]

Hi @MatsPalmgren

Before looking at this example that I am looking at the compatibility information here: mdn/browser-compat-data#15666. Can you please confirm my assumptions?

Essentially those assumptions are:

• siblings in a nesting level are assigned a new counter. My assumption is that it is just one counter they all share initially.
• calling counter-reset on an element creates a new counter and assigns it to just that element. Siblings before and after keep the original (shared) counter.
• calling counter-set on an element resets the value of the shared counter assigned to that element.
• The original example was a bit odd because it reset just one sibling half way through the list so previous and subsequent numbering was unaffected. The likely intent was that the number changed after calling counter-reset and continued. To do that you would call counter-set

About right?

[sideshowbarker]

@MatsPalmgren This is waiting on your response to #2793

[sideshowbarker]

@hamishwillee Given the lack of response, how should we proceed with this?

[hamishwillee]

@sideshowbarker IMO this is a valid unassigned issue - so we need a volunteer to look at it.

The easy way to do this would be to simply take the suggestion here: #2793

I was hoping to do a more thorough fix up, because the broken example hightlights some common misunderstandings with how reset work - which I was trying to verify in #2793

I could do this, but not sure I'm the best CSS person to take it on.

[github-actions]

It looks like this is your first issue. Welcome! 👋 One of the project maintainers will be with you as soon as possible. We appreciate your patience. To safeguard the health of the project, please take a moment to read our code of conduct.