✨ NEW: Initial handling of numbering and references

executablebooks / markdown-it-docutils

A markdown-it plugin for implementing docutils style roles/directives.

https://executablebooks.github.io/markdown-it-docutils/

MIT License

12 stars 8 forks source link

✨ NEW: Initial handling of numbering and references #14

Closed rowanc1 closed 2 years ago

rowanc1 commented 3 years ago

Initial take at #10

At the moment the implementation is as follows:

state.env.docutils = {
  targets: Record<string, Target>
  references: Reference[]
  numbering: Record<TargetKind | string, number>
}

Currently I am pushing the reference tokens into those states with the functions newTarget (e.g. called when a labelled figure is created) and resolveRefLater (e.g. called for ref, numref, etc.).

I will call out the logic in a review. Looking forward to comment from @chrisjsewell.

Adds functionality for:

[x] eq
- [x] %s, {name}, {number}
[x] numref
- [x] %s, {name}, {number}
[x] ref
- [x] %s, {name}, {number}
[x] figures
[x] math_block

rowanc1 commented 2 years ago

@chrisjsewell finding myself wanting to make changes that are in the other branches just to get started on this again.

Looking forward to getting the other 3 PRs moved ahead and then will dive into some of the comments. I will add a few more tests and document it some more from the outside, as discussed I think we can take this in a few different stages (e.g. single-doc, multi-doc).

rowanc1 commented 2 years ago

Rebased on the other three branches. I will put a bit more work into this and I think it will be good for a first pass of state!

rowanc1 commented 2 years ago

@fwkoch @chrisjsewell this is good to come in in my opinion. Could one of you please review!

Adds three new role directives for referencing (eq, numref, ref) and has basic state management in place. That state management is not exposed externally, so it is easy to refactor it as we go and learn more. This unblocks downstream work on mystjs that @fwkoch is getting into this week!

The references currently look like this:

There is some playing that we will have to do on a numbering pass to make sure that amsmath and dollarmath get picked up ok, that will be the responsibility of Myst, but I introduced/refactored a test to have a fake renderer here.

fwkoch commented 2 years ago

I just moved over a few tests from mystjs which belong here. Also added figure/math numbering.

rowanc1 commented 2 years ago

Numbering and reference roles are updated and work in vscode.

rowanc1 commented 2 years ago

Note this is on top of the packaging PR #26, which should be merged first.

rowanc1 commented 2 years ago

This should now be good to go @chrisjsewell. We will have some other numbering in the mystjs package, but this will remain necessary for myst-vs-code to work, which will continue to rely on markdownit.

The more complicated multi-document referencing will happen in mystjs. There is also some additional work to get this hooked up to dollarmath/amsmath. That work is in progress here, but requires this branch (and another one incoming) to pass tests!

https://github.com/executablebooks/mystjs/pull/35

My recommendation is:

Merge https://github.com/executablebooks/markdown-it-docutils/pull/28
Rebase this PR, and merge (I can do that once the other is merged, some tests to fix likely)
Release a version of markdown-it-docutils
Continue on MystJS PR, that will require some more of the options/args exposed from docutils in a standardized way. Start of a branch is pushed to this repo.

Thanks @chrisjsewell.

rowanc1 commented 2 years ago

Double checked the rebase. Tests and fixtures are there correctly, tests pass!