🔢 Enable continuous numbering across pages

[fwkoch]

This adds an extra key to numbering fields - continue. If true, the numbering of that type will continue counting from the previous page.

This also adds title/page-level enumeration (which, combined with continue means you can have numbered chapters).

Finally, this cleans up how frontmatter numbering heading_# relates to page heading depths. Now, the user-defined frontmatter levels match the user-defined heading depths, even if transforms have changed the depths in the mdast (for normalization, title lifting, etc).

[agoose77]

What is this blocked on? Can I help in any way?

[rowanc1]

I think it was blocked on requirements as we got a bit confused on how to actually do it!

[fwkoch]

I don't think there is anything critical blocking this - I just stepped away from it and have not come back. The biggest thing I could use some input on is the frontmatter fields:

In numbering on a page, you can now specify start: <number> (if you want to start counting at a specific number) or continue: true (if you want to continue counting from the previous page). However, as these are separate fields, you can specify both, e.g.:

numbering:
  figure:
    start: 3
    continue: true

In that case, it is ambiguous which takes priority. So, I think we should reconsider this frontmatter so this ambiguity is not possible. Maybe that means start: number | 'continue' or something? So you can either specify a starting number or say "continue from previous page." Or, we could just leave start and continue but introduce a validation error if both are defined... Or maybe something else?

Beyond that, this PR just needs some more testing and bug fixing - the continuous numbering still doesn't quite work as expected everywhere.

[changeset-bot]

🦋 Changeset detected

Latest commit: c31f811

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
myst-frontmatter	Patch
myst-transforms	Patch
myst-spec-ext	Patch
myst-common	Patch
myst-cli	Patch
myst-config	Patch
mystmd	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[rowanc1]

Picking this back up with franklin to get it over the line now!

[fwkoch]

This is finally ready to go - a lot in here is not pretty, but there are quite a few new end-to-end test cases to test the new functionality.

A bunch of enhancements still need to come for more flexibility with numbering:

• Allow enumeration on titles in table of contents #1786
• Allow heading/title enumeration values in other numberings #1787
• Modify numbering frontmatter to customize "reset after" behavior #1788

[fwkoch]

Related small theme pr: jupyter-book/myst-theme#525

[rowanc1]

OK - this is good to go! Been testing with @fwkoch interactively for the last few days and pretty happy with these new capabilities. There is more to do, but this is a bit step forward.

[paulskrzypczyk]

not sure if this is the correct place to post (apologies in advance if it is wrong).

After this update, all my exercises are now continue to number across pages. For example, in chapter 2, my first exercise is now 2.5, whereas previously it was 2.1. I haven't changed anything, so is this the expected behaviour or a bug? From what I'm ready above, I thought the default behaviour would be to reset the numbering within in chapter (as previously?) If this isn't a bug, could you advise on what I need to add to change the behaviour?

[fwkoch]

@paulskrzypczyk - your post here is great. I appreciate the report.

It does sound like bug rather than something you need to change - I need to investigate a little further and follow up.

[fwkoch]

@paulskrzypczyk - Ok, I tried to recreate this in one of your repositories (https://github.com/paulskrzypczyk/qm-lecturenotes-new), but for that one, the numbering behaved as I expected. Running myst start with no changes to frontmatter, numbers reset:

then setting equations: continue under numbering I get the continuous numbering:

Can you point me to the specific project where you are seeing this issue? Or if it's private, maybe a minimal example?

[paulskrzypczyk]

Hi Franklin, it is the exercise numbering which is continuous, not the equations (which are numbering correctly). It is indeed the repo you're looking at. At the end of each chapter you'll see a collection of exercises. In chapter, I now see

and in chapter 3

etc

Hope this helps clarify

[fwkoch]

Thank you - yes I just noticed that 😅 And I do see the same behavior.

[fwkoch]

@paulskrzypczyk - This should be fixed here: #1824 - I'll get that released tonight or tomorrow morning!

Thanks again for reporting the issue! (And sorry for my poor reading comprehension, hah.)