Convert between inline link and reference link

[MonsieurMan]

The original post has been merged into the formal proposal.

Proposal

Overview

Markdown provides multiple ways to create links. It would be useful to have refactorings that convert between inline and reference links. Doing it manually all the time makes me quite sad.

There are totally 12 kinds of conversions.

The following seem always feasible:

Inline <=> Full <- Collapsed <- Shortcut

From	To
Inline	Full
Full	Inline
Collapsed	Inline
Collapsed	Full
Shortcut	Inline
Shortcut	Full
Shortcut	Collapsed

Out of reliability and compatibility concern, the other 5 conversions are possible only under certain circumstances.

In practice, the 5 kinds below should be enough:

From	To
Inline	Full
Inline	Collapsed
Full	Inline
Collapsed	Inline
Shortcut	Inline

The Inline -> Collapsed conversion is available only if no brackets ([ or ]) are next to the link, and the link text matches JavaScript regular expression /^[\w-]+$/ (only contains ASCII letters, digits, underscore, and hyphen).

Cases

• One inline link to full or collapsed reference link.

  • Use existing link reference definition if possible.
  • In addition to syntax requirements, if the user provides definitely error-prone label text, such as containing consecutive internal whitespace, reject it.
  • Normalize the link reference definition.
    • Remove unnecessary spaces in label.
    • Escape URI according to RFC 3987. When encountering IPv6, use RFC 3986 with RFC 6874.
    • Enclose URI by < and >.
    • Simply the representation of link title. Reduce escape sequences. Try straight double-quote characters (") first, then '.

  <!-- From: -->
  [My [simple] link](<uri uri> 'title \'n )(title')
  
  <!-- To: -->
  [My [simple] link][2_ref-def]
  
  [2_ref-def]: <uri%20uri> "title 'n )(title"

• All inline links with the same destination and title to full reference links.

  <!-- From: -->
  A [fox](<uri uri> 'title') jumped over a lazy dog. The [fox][] was brown. [It](uri%20uri (title)) moved very quickly.
  
  [FOX]: <uri%20uri> "title"
  
  <!-- To: -->
  A [fox][fox] jumped over a lazy dog. The [fox][] was brown. [It][fox] moved very quickly.
  
  [FOX]: <uri%20uri> "title"

• One reference link to inline link.

  • Normalize the link destination and title.

• All reference links with the same link reference definition to inline links.

  <!-- From: -->
  A [fox] jumped over a lazy dog. The [fox][] was brown. [It][fox] moved very quickly.
  
  [FOX]: <uri uri> 'title'
  
  <!-- To: -->
  A [fox](<uri%20uri> "title") jumped over a lazy dog. The [fox](<uri%20uri> "title") was brown. [It](<uri%20uri> "title") moved very quickly.

• Code spans and code blocks should remain untouched.

  <!-- Do not touch: -->
  `[dog][foo]`
  
  ```markdown
  [foo] [bar](/uri)
  ```
  
  [foo]: /uri

• Consecutive links should remain untouched. Too dangerous to process them.

  <!-- Do not touch: -->
  [link1](/uri1 "title")[link2](uri2)[link3](</uri 3>)
  
  <!-- Below is OK: -->
  [link1](/uri1 "title") [link2](uri2) [link3](</uri 3>)

References

• Unicode case folding
• Links | CommonMark Spec
• Links | Markdown Syntax | John Gruber
• Beyond Markdown | CommonMark Discussion
• Shortcut Link Questions | CommonMark Discussion
• Convert inline link to reference link #736
• Extract Variable | Refactoring.com

[MonsieurMan]

Here is a node.js program I found if it can help:
https://github.com/bjfletcher/convert-markdown-inlined-links-to-references/blob/master/main.js

[yzhang-gh]

I agree that it might be useful. But I probably have little time for this in the near future. Let's see whether there is somebody can help.

[MonsieurMan]

I don't have that much time the two next weeks neither but I could definitely help creating it after. 😃

[RoyiAvital]

Is there any progress on this?

Could you make it work just like in StackExchange editor?

[yzhang-gh]

Thanks for asking.

Technically, it is not hard (I guess). But there are many corner cases to take into account. It would be great if anyone can help as now I only have limited time for this extension (for crucial bugs or small fixes).

[RoyiAvital]

There is a reference Python code here: https://stackoverflow.com/a/30919298.
It is not perfect, I wish I knew enough Python to fix it.

But if you copy it to JS and implement the feature behind an opt in option I can test it and submit the edge cases.
Probably from there things will get better, right?

[yzhang-gh]

Well, if you look at the "Cases" section in the origin post of this issue, you will see a lot of implementation details, which are not considered in the link you mentioned. For example,

<!-- From: -->
[My [simple] link](<uri uri> 'title \'n )(title')

<!-- To: -->
[My [simple] link][2_ref-def]

[2_ref-def]: <uri%20uri> "title 'n )(title"

note \' in the title field. Also,

Inline links with the same destination and title should refer to the same reference link definition.

Code spans and code blocks should remain untouched.

and more.

As I said, it is not technically hard, but requires a certain amount of time. It cannot be a one-pass regex replacement but needs a reasonable workflow (e.g. A rough thinking tells me it should have 3 (maybe 2) steps: parse existing reference link definitions, identify inline/reference links, and then transform). If anyone can make a PR, I'm happy to review it.