Convert baseline inline links to point of reference links

[schrolla]

💡 Summary

Update baselines to use the point of reference link style rather than inline style for all links. The point of reference style allows inline link references to be small and not upset reading of source and allows link URLs to be set into their own separate sections. The new style would enhance readability and maintenance of the baseline markdowns.

Motivation and context

You can separately define and reference links in Markdown documents using the "point of reference style" rather than the "inline link" style we've used to date. This means when you are embedding links in a paragraph, you don't have to ruin the flow or line width to make the URL work.

Implementation notes

You can just insert the reference tag (e.g., [link name][]) and then anywhere else in the same document, define the reference via [link name]: <URL>.
For example, instead of

The quick brown fox jumped over the lazy [dog](https://www.example.com/doggosFTW/long/uri/that/messes/with/my/80characterwidth/linelimit).

you could just have the following:

The quick brown fox jumped over the lazy [dog][].
[dog]: https://www.example.com/doggosFTW/long/uri/that/messes/with/my/80characterwidth/linelimit

And both will render the same way with "dog" being a link to the referenced URL. You can include the definition at the start of the doc, end of the doc, after the relevant paragraph... wherever. I recommend defining link references at the end of paragraphs or sections so the definition is still within easy reach and maintainers remember to update and review the links themselves.

Acceptance criteria

• Determination has been made to implement point of reference link style
• Style guide has been updated to show the preferred style for links
• Confirmed that point of reference links are carried over in converted markdown documents successfully
• All baseline documents have been updated with the preferred link style and reviewed for accuracy and functional links

[twneale]

This Python script should be able to do the conversion:

import sys
import re

with open(sys.argv[1]) as f:
    data = f.read()

rgx = r'(?P<ref>\[[^\]]+\]+)\s*\((?P<url>[^\)]+)\)'
matches = list(re.finditer(rgx, data))

# Blow up if same link name used twice.
refs = set()
for m in matches:
   if m.group('ref') in refs:
       raise Exception('Duplicate link ref found')
   refs.add(m.group('ref'))

data = re.sub(rgx, lambda m: m.group('ref') + '[]', data)
for m in matches:
    data += f'{m.group("ref")}: {m.group("url")}\n'

sys.stdout.write(data)

To run it:

python fixthing.py aad.md > aad.md