Add function to update markdown link references in a document

Prerequisites

• Accepted Idea: Proposals in this project are created based on ideas that have been marked as Accepted in their Discussion. Before you file an issue for a feature or change, create a discussion. If you file an issue without a discussion, the team may convert it into one.
• Existing Issue: Search the existing issues and discussions for this repository. If there is an issue or discussion that fits your needs do not file a new one. Subscribe, react, or comment on that issue or discussion instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Add Get-Foo cmdlet to Documentarian module" instead of "New cmdlet."

Module

Documentarian

Summary

As a content author, I want to be able to run a command to inspect a markdown file and canonically update link references to avoid needing to maintain them by hand.

Details

This functionality could be provided by an Update-ReferenceLink function that:

1. Inspects a given document (by path or input) to find existing reference links and definitions
2. Deduplicates the references, updating the content to use the deduplicated references
3. Renames the references in numerical order of appearance.
4. Adds the updated reference definitions at the bottom of the file after an HTML comment.

For example, it would convert this:

# Article Title

This is some [example][ex] text that [has](/relative.md) links
throughout it. When it's [updated][ex], the links are [replaced][a]
in a deterministic [way][b]. When a link is reused with a different
[reference][ref], it's deduplicated.

At the end of the process, the link references are [numerical][n1]
in their order of [appearance][ex].

[ex]: https://some.site.com
[a]: https://another.site.com
[b]: ./local/file.md
[ref]: ./local/file.md
[n1]: https://last.site.com

To this:

# Article Title

This is some [example][01] text that [has](/relative.md) links
throughout it. When it's [updated][01], the links are [replaced][02]
in a deterministic [way][03]. When a link is reused with a different
[reference][03], it's deduplicated.

At the end of the process, the link references are [numerical][04]
in their order of [appearance][01].

[ex]: https://some.site.com
[a]: https://another.site.com
[b]: ./local/file.md
[ref]: ./local/file.md
[n1]: https://last.site.com
<!-- Link Reference Definitions -->
[01]: https://some.site.com
[02]: https://another.site.com
[03]: ./local/file.md
[04]: https://last.site.com

By default:

• The reference links use two numerals for their definition, supporting up to 99 unique links on a page.
• The previous reference links aren't removed, only the actual references are munged.
• Non-reference links are ignored.

With parameters, the default behavior can be changed:

• Use the ConvertInline parameter to convert all inline style ([<text>](<definition>)) links in the document to reference links before deduplication and updating.
• Use the ReferenceScheme parameter to choose between Numeral and Alphabetical reference link naming, where Numeral is the default and defines link references as 01 through 99 and Alphabetical numbers links aa through zz (aa followed by ab and so on).
• Use the Force parameter to update the document and remove the old link reference definitions.
• Use the NoComment parameter to skip writing the HTML comment or the CommentText parameter to define a custom note instead of the default.
• Use the NoWrite parameter to skip writing the file at all.
• Use the PassThru parameter to return the munged content to the caller.

For example:

# Update article.md in place, converting all inline-style links to
# reference links and removing the old reference link definitions.
Update-ReferenceLink -Path ./article.md -ConvertInline -Force
# Don't modify article.md but do return the munged content.
Update-ReferenceLink -Path ./article.md -NoWrite -PassThru

Use the proposed Update-ReferenceLink function and the article.md examples in the issue as the starting entry points. Compare the default behavior and parameters described there, including ConvertInline, ReferenceScheme, Force, NoWrite, and PassThru. Done means markdown reference links are deduplicated and renamed deterministically while honoring the listed options.