convert inline links to references?

[anarcat]

Context

I'm an apologetic reference link fan. For me, they make the source document easier to read, and I often send markdown documents by email (for various reasons) where it is particularly important to get those pesky links out of the way.

Proposal

It would be nice if mdformat could (optionally? in a plugin?) completely convert all inline links to references in a document. It's not a simple task, as references might clash with each other, so there needs to be some tracking for that...

I understand if that can't be part of mdformat per se, but I figured i would use this space to open up discussion about this, perhaps someone else has already found and fixed that problem themselves?

Thanks!

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[pawamoy]

Super interested by this as well. Would be happy to try and send a PR if a maintainer can provide some initial guidance 😄

[nuke-web3]

Would love to see this - but it does mean this tooling needs to make very opinionated decisions about how to make the translation from inline -> reference links work

• what is the ID system enforced? ( [text used][ID])
• what is the location of reference links in a page? (always at the end?)
  • how are references sorted? (ID alphanumeric decending?)
• is the inverse possible? (replace ID with URL)

[pawamoy]

Good questions.

• ID system: I'd say, use the text as-is, i.e. [some text] or [some text][], and [some text]: url. The user can then change the ID and mdformat would respect it next times it formats.
• location: I think it currently always puts all references at the end of the page
• sorting: I'd say sort on IDs yes, lower case, 0 -> 9 then a -> z
• seems doable. Might be done in later PRs?

We just need updates from maintainers 🙂

[hukkin]

Fun fact: mdformat was inline links only originally #32

---

This shouldn't be hard to do at all. Mdformat already places references at the end of the document, orders alphabetically, canonicalizes labels to lower case, removes duplicate refs, removes unused refs etc. so much of what has been discussed here is already implemented.

It's just that we have to come up with the link label completely on our own.

I'd say, use the text as-is

This isn't a good enough spec. The link text can be empty string, link label cannot. Link text is unlimited in size, link label is limited to 999 characters. There's probably more pitfalls.

An alternative is to number the labels, 1, 2, 3, 4, ... . There are certainly documents that have more than 1000 links though.

So I think in extreme cases we probably have to resort to some kind of hash values.

So I'm not sure about this at all. If anyone wants this to happen, please come up with the perfect spec and we can consider. 😄

---

Maybe even more importantly, I have a feeling there's more users that don't want this feature than those who do. I may be wrong. If there's anyone who has a use case where this feature would really suck, please write in this thread! 😄

In any case, the plugin API remains to be there for people who want to extend mdformat.

[pawamoy]

Thanks for the update @hukkin, and for pointing out the shortcomings of the proposal 🙂 I might try to write a plugin for that! That would be a good first exercise to get to know mdformat's internals 😄