MyST-Parser
MyST-Parser copied to clipboard
More fine-grained control over what is an "external link"
Context
I have a use case where I am mixing MyST .md files and docutils .rst files, and I would like to link between the two.
Linking from rst to md is fine, I can pass a relative link that ends in .html to docutils, and it swallows this with no complaints, and generates the correct output.
Linking from md to rst is not fine, because MyST has a special treatment for links:
- if myst_all_links_external is False, then links without explicit schemes are treated as "internal" links to be resolved according to a particular algorithm. If resolution fails, then the link instead generates a system error message - very ugly!
- if myst_all_links_external is True, then the relative link works. However, I then lose the ability to do internal cross-referencing like the example
[reference](syntax/referencing)
in the docs - and also #640, if and whenever that is implemented.
Proposal
What would be better is if MyST failed gracefully and did not generate a system error message when myst_all_links_external is False
, and just allow the failed resolution (i.e. of a .html relative link) to go through just as normal rst-docutils does.
I am not sure why the current behaviour is so strict, but if this strictness is really desired, then enabling this more relaxed behaviour via a config flag like myst_lenient_internal_links
would also be fine.
Tasks and updates
- [ ] decide whether the current strictness is really necessary
- [ ] implement leniency either via a new config option, or replace the current behaviour
heya, this and #640 are essentially covered in #613
That sounds great! Just wanted to add that my own use-case is docutils only and does not depend on sphinx, so I hope all the features that #613 talks about continue to work outside of sphinx too.