-
Notifications
You must be signed in to change notification settings - Fork 197
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
♻️ REFACTOR: Parsing logic of Markdown links #467
Conversation
This sounds pretty reasonable to me. This sounds like a nice improvement. A few thoughts:
|
yes, |
Codecov Report
@@ Coverage Diff @@
## master #467 +/- ##
==========================================
- Coverage 90.30% 90.23% -0.07%
==========================================
Files 16 16
Lines 1990 2017 +27
==========================================
+ Hits 1797 1820 +23
- Misses 193 197 +4
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report at Codecov.
|
👍 |
thanks @chrisjsewell -- I think this is a nice improvement. I particularly like that links to non-source documents are migrated to download links. I think that is nice behaviour. 👍 |
I used to be able to link to local HTML (post-build) files but it seems that is no longer the case? |
This PR aims to clarify and improve the parsing of Markdown links, i.e.
[Text](link)
Related issues: #193, #402, #411, #435
Current logic
http:
) and that scheme is inmyst_url_schemes
ormyst_url_schemes=None
, then create an external link, e.g. `Text#
(i.e. a fragment), then also create an external link (unless theheading_anchors
extension is active)addnodes.pending_xref
of type "myst"After (4), the "myst"
pending_xref
are then intercepted in theMystReferenceResolver
post-transform (after all documents have been parsed), and the reference resolved similar to the sphinxany
role:They check the reference against all reference types, taking the first hit as the target and emitting a warning, if none or multiple targets are found.
Different to the standard
any
role sphinxReferenceResolver
, the myst one allows for (a) matching document paths with their extensions, e.g.[Text](path/to/other.md)
, and (b) parsing nested syntax as part of the text, e.g.[Text **bold**](link)
.there is also a little more complication, when using the
heading_anchors
extension, to match generated header targets, e.g.[Text](document.md#header-1)
Shortcomings
(2) I believe originally came from recommonmark, but I think it is probably too permissive and unexpected.
(3) Is definitely not ideal, for docutils only use
(4) What is currently not handled, is links to "non-sphinx" files, e.g. non RST or Markdown files like
[Text](path/to/file.txt)
. In sphinx we would want to use thedownload
role for this, to ensure that the referenced files are copied into the build directory and the endhref
points to that.Current Improvements
This PR is in draft, but current improvements are:
myst_all_links_external=True
, which simply directs for all links to be rendered as external links.I think this can be helpful for especially docutils use
download_reference
node.Perhaps there can be some more configuration,
but one thing I want to balance is (a) having sensible defaults, (b) allowing for some configuration, but (c) not having too much allowed configuration, which would be confusing to basic users and also then need to be replicated in any future MyST parser implementations.
Questions
#
are external links?I'll expand on this a bit more at a later data, but welcome comments from interested parties: @choldgraf, @mmcky, @rowanc1, @cpitclaudel, etc