Add lint for a link reference without a corresponding link definition (or vice versa)

[gibfahn]

Often (especially when refactoring) links using the definition/reference style will get broken. It would be useful for markdownlint to catch this.

Two examples are:

Link Ref without Def

See [Docs][] for more info.

<!-- Should have a link definition below like:
[docs]: https://example.com
-->

Link Def without Ref

See [New Docs][] for more info.

<!-- None of the link definitions match the link reference above. -->
[docs]: https://example.com

[jasonsnell]

Yes, agreed with this completely. A friend and I were working on a small standalone Markdown linter for writing purposes and this was actually our first feature! So strange that it's not in there.

[DavidAnson]

@jasonsnell, I think I listen to your podcasts sometimes. :) Yes, there is a set of link-based rules in the queue I just haven't got to yet.

[nschonni]

I usually use https://www.npmjs.com/package/markdown-link-check since when you start to link check outside of the same document, you need to have a concept of a layout and replacements

[gibfahn]

Just tried markdown-link-check with the snippets from above:

echo 'See [Docs][] for more info.

<!-- Should have a link definition below like:
[docs]: https://example.com
-->' > ref_without_def.md
docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/ref_without_def.md

echo 'See [New Docs][] for more info.

<!-- None of the link definitions match the link reference above. -->
[docs]: https://example.com' > def_without_ref.md
docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/def_without_ref.md

Output (0 exit code):

FILE: /tmp/ref_without_def.md
  No hyperlinks found!

  0 links checked.

FILE: /tmp/def_without_ref.md
  No hyperlinks found!

  0 links checked.

so doesn't actually seem like it catches this case, possibly because it considers having extra refs/defs to be an okay thing to do (whereas for me it's nearly always copy-pasta, or someone forgetting how the defs/refs actually work.

[nschonni]

Right, I missread this, but it looks like a duplicate of #144

[DavidAnson]

Agree, I'll probably try to add this for the next (not pending) release.

[nschonni]

Here is the remark-lint version of this rule https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references to see if they have any edge case code that might be needed

[jasonsnell]

FWIW, speaking as a professional writer who writes exclusively in markdown, forgetting a link reference either way happens way more than you'd think!

…

On Dec 24, 2021, at 3:15 AM, Gibson Fahnestock ***@***.***> wrote:  Just tried markdown-link-check with the snippets from above: echo 'See [Docs][] for more info. <!-- Should have a link definition below like: [docs]: https://example.com -->' > ref_without_def.md docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/ref_without_def.md echo 'See [New Docs][] for more info. <!-- None of the link definitions match the link reference above. --> [docs]: https://example.com' > def_without_ref.md docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/def_without_ref.md Output: FILE: /tmp/ref_without_def.md No hyperlinks found! 0 links checked. FILE: /tmp/def_without_ref.md No hyperlinks found! 0 links checked. so doesn't actually seem like it catches this case, possibly because it considers having extra refs/defs to be an okay thing to do (whereas for me it's nearly always copy-pasta, or someone forgetting how the defs/refs actually work. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.

[gibfahn]

Right, I missread this, but it looks like a duplicate of #144

Ahh, good point, failed to find that in the issue search.

[DavidAnson]

Two new rules will be available in the next release of the library:

• https://github.com/DavidAnson/markdownlint/blob/next/doc/Rules.md#md052
• https://github.com/DavidAnson/markdownlint/blob/next/doc/Rules.md#md053

They will report errors for:

• Link and image references missing a label
• Link/image reference definitions that are unused
• Link/image reference definitions that are duplicated

The latter two scenarios can be automatically fixed by the library (by deleting the unneeded reference definition).

/cc @jasonsnell

[jasonsnell]

thank you @DavidAnson ! My friend might have invented Markdown? ;-)

[DavidAnson]

@jasonsnell Hopefully the idea of a Markdown linter does not offend him too much.

[jasonsnell]

He's working on a little one of his own for person writing use, much less comprehensive than this one. I think he likes the idea! But I don't want to speak for him.

[DavidAnson]

@jasonsnell Cool. If there's anything ya'll think I should be doing here to make it more compelling (other than adding more rules), please let me know.

For example: editor integration. I happen to think the VS Code integration is pretty good (because I wrote it), but maybe you have a different favorite editor.

https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint

[waldyrious]

@DavidAnson could there be an option for MD052 to force checking in shortcut link syntax? It could default to false, but in my case markdownlint was missing a reference-type link with an undefined target because of this, and I'd like to set up a check to avoid that in the future.

Happy to open a separate issue if that's preferred.

[DavidAnson]

@waldyrious See #845

[waldyrious]

@DavidAnson thanks for the pointer. I read the discussion and code in the PR and maybe I'm missing something, but it seems to be about enforcing the inline-vs-reference link style, rather than enforcing that, for reference-style links, the shortcut type may not be used.

Additionally, there seem to be different notions of what a shortcut-type reference link means. In the relevant commit from that PR, it seems to be [foo][], whereas in Rules.md (across the entire file, but especially in the MD052 section) it seems to be understood as just [foo]. For clarity, I am interested in an option to make MD0052 process the latter the same way it processes the former.

[DavidAnson]

Per the specification at https://spec.commonmark.org/0.30/#links:

There are three kinds of reference links: full, collapsed, and shortcut.

I try to be accurate when referring to this, but may have made a mistake somewhere in the documentation.

You are right that the issue I linked to focuses more on in line styles. You may be asking for a similar rule for the different kinds of reference link.

[DavidAnson]

Please open a new issue for a new rule to specify which types of reference links to allow. Thank you!

[waldyrious]

Ah, I see. So the [foo][] syntax is called "collapsed", not "shortcut". That's good to know, thanks!

I'll open a new issue.

[waldyrious]

Btw, responding more directly to the suggestion of

a new rule to specify which types of reference links to allow

I do agree it might be a good addition to the upcoming MD054/link-style rule to have an option to specify whether reference links should use shortcut, collapsed or full syntax. Such an option would not be my preferred resolution for the issue I had with shortcut-style reference links (which is why I made a slightly different request in #915), but I'm happy to open a separate issue for the option to customize MD054/link-style once #845 is merged. Does that sound OK?

[DavidAnson]

I'd suggest proposing a new reference link style rule as a different rule because MD054 already feels tricky enough.