Vscode-markdown: 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]
  
  
  




• 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.
  
  <!-- To: -->
  A [fox][fox] jumped over a lazy dog. The [fox][] was brown. [It][fox] moved very quickly.
  
  
  




• 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.
  
  <!-- 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.

  `````markdown <!-- Do not touch: --> dog`

  [foo] [bar](/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

• Links | CommonMark Spec
• Links | Markdown Syntax | John Gruber
• Beyond Markdown | CommonMark Discussion
• Shortcut Link Questions | CommonMark Discussion
• https://github.com/yzhang-gh/vscode-markdown/issues/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. 😃