search

jupyter-book / myst-spec

MyST is designed to create publication-quality, computational documents written entirely in Markdown.
https://mystmd.org/spec
MIT License
14 stars 6 forks source link

crossReference kind #24

Open fwkoch opened 2 years ago

fwkoch commented 2 years ago

This is quite limited in the spec to: eq, numref, ref, doc https://github.com/executablebooks/myst-spec/blob/main/schema/references.schema.json#L37 (even doc is missing in this schema file) - this matches the jupyterbook myst documentation https://jupyterbook.org/content/references.html#reference-figures

This feels a little mixed up: ref and numref don't specify the target type, it may be a header, figure, table, etc. On the other hand eq and doc specify the target type (but don't differentiate between reference or numbered reference).

Should these kinds be specific in their target type? math table figure etc? Or should they simply be references to be resolved later? There are pros/cons each way - e.g. the former requires more validation but allows knowledge of the target type without resolving the reference every time.

We can also introduce kind + domain, like sphinx does here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-math-domain

rowanc1 commented 2 years ago

Some state management is here: https://github.com/executablebooks/mystjs/blob/main/src/mdast/state.ts