Heading numbering

[multimeric]

I wanted to have heading numbering, like this:

Now, I wrote some CSS that solves this problem (at least for 2 subheadings, although it can be extended to include more). I'm wondering if I could push it upstream, either into:

• The base theme, but locked behind an HTML class so that users can trivially add it, or
• Into the docs so that people can easily find a way to add numbering

The CSS in question is:

  body {
    counter-reset: heading 1;
    counter-reset: subheading 1;
  }

  h2:before {
	content: counter(heading)". ";
  }

  h2 {
    counter-reset: subheading;
    counter-increment: heading;
  }

  h3:before {
    counter-increment: subheading;
    content: counter(heading) "." counter(subheading) ". ";
  }

[agitter]

Would Pandoc's section numbering support your use case? If it does, then we could work on a documentation pull request without the custom CSS. This has come up multiple times (see also #442 for related discussion), so I think adding it to USAGE.md is a good idea.

[multimeric]

Good point. I went for a CSS approach because in general I feel like using CSS gives you more control in a user-friendly way. But since pandoc provides this feature it might be lower friction. It's a shame that issue didn't come up when I searched. On the other hand though, that pandoc issue (jgm/pandoc#5071) seems like it might be a problem here, and my CSS solution is actually suggested in the pandoc thread.

If we do go with the pandoc solution I think it might be better to not enable numbering by default, but since it's trivial to add number-sections: true, we just document that.