[GH-ISSUE #456] Add lint for a link reference without a corresponding link definition (or vice versa)

kerem commented

2026-03-03 01:26:21 +03:00

Owner

Originally created by @gibfahn on GitHub (Nov 5, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/456

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

Originally created by @gibfahn on GitHub (Nov 5, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/456 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 ```markdown See [Docs][] for more info.  ``` ## Link Def without Ref ```markdown See [New Docs][] for more info.  [docs]: https://example.com ```

kerem

2026-03-03 01:26:21 +03:00

closed this issue
added the
fixed in next

new rule
labels

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@jasonsnell commented on GitHub (Dec 16, 2021):

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.

@jasonsnell commented on GitHub (Dec 16, 2021): 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.

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 16, 2021):

@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.

@DavidAnson commented on GitHub (Dec 16, 2021): @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.

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@nschonni commented on GitHub (Dec 16, 2021):

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

@nschonni commented on GitHub (Dec 16, 2021): 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

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@gibfahn commented on GitHub (Dec 24, 2021):

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.

@gibfahn commented on GitHub (Dec 24, 2021): Just tried markdown-link-check with the snippets from above: ```shell echo 'See [Docs][] for more info. ' > 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.  [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.

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@nschonni commented on GitHub (Dec 24, 2021):

Right, I missread this, but it looks like a duplicate of https://github.com/DavidAnson/markdownlint/issues/144

@nschonni commented on GitHub (Dec 24, 2021): Right, I missread this, but it looks like a duplicate of https://github.com/DavidAnson/markdownlint/issues/144

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 24, 2021):

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

@DavidAnson commented on GitHub (Dec 24, 2021): Agree, I'll probably try to add this for the next (not pending) release.

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@nschonni commented on GitHub (Dec 24, 2021):

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

@nschonni commented on GitHub (Dec 24, 2021): 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

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@jasonsnell commented on GitHub (Dec 24, 2021):

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.
' > 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.

[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.

@jasonsnell commented on GitHub (Dec 24, 2021): 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. > > ' > 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. > >  > [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.

kerem commented

2026-03-03 01:26:22 +03:00

Author

Owner

@gibfahn commented on GitHub (Dec 27, 2021):

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

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

@gibfahn commented on GitHub (Dec 27, 2021): > Right, I missread this, but it looks like a duplicate of #144 Ahh, good point, failed to find that in the issue search.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 2, 2022):

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

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

@DavidAnson commented on GitHub (Jun 2, 2022): 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

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@jasonsnell commented on GitHub (Jun 22, 2022):

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

@jasonsnell commented on GitHub (Jun 22, 2022): thank you @DavidAnson ! My friend might have invented Markdown? ;-)

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 22, 2022):

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

@DavidAnson commented on GitHub (Jun 22, 2022): @jasonsnell Hopefully the idea of a Markdown linter does not offend him too much.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@jasonsnell commented on GitHub (Jun 22, 2022):

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.

@jasonsnell commented on GitHub (Jun 22, 2022): 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.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 22, 2022):

@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

@DavidAnson commented on GitHub (Jun 22, 2022): @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

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@waldyrious commented on GitHub (Jul 21, 2023):

@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.

@waldyrious commented on GitHub (Jul 21, 2023): @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.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 21, 2023):

@waldyrious See #845

@DavidAnson commented on GitHub (Jul 21, 2023): @waldyrious See #845

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@waldyrious commented on GitHub (Jul 21, 2023):

@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.

@waldyrious commented on GitHub (Jul 21, 2023): @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](https://github.com/DavidAnson/markdownlint/pull/845/commits/701dc8e379748290ba5f3f654d22635f4ad43113), it seems to be `[foo][]`, whereas in [Rules.md](https://github.com/DavidAnson/markdownlint/blob/v0.29.0/doc/Rules.md) (across the entire file, but especially in the [MD052 section](https://github.com/DavidAnson/markdownlint/blob/v0.29.0/doc/md052.md)) 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.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 21, 2023):

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 commented on GitHub (Jul 21, 2023): 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.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 21, 2023):

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

@DavidAnson commented on GitHub (Jul 21, 2023): Please open a new issue for a new rule to specify which types of reference links to allow. Thank you!

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@waldyrious commented on GitHub (Jul 22, 2023):

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 commented on GitHub (Jul 22, 2023): Ah, I see. So the `[foo][]` syntax is called "collapsed", not "shortcut". That's good to know, thanks! I'll open a new issue.

kerem commented

2026-03-03 01:26:23 +03:00

Author

Owner

@waldyrious commented on GitHub (Jul 22, 2023):

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?

@waldyrious commented on GitHub (Jul 22, 2023): 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?

kerem commented

2026-03-03 01:26:24 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 22, 2023):

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

@DavidAnson commented on GitHub (Jul 22, 2023): I'd suggest proposing a new reference link style rule as a different rule because MD054 already feels tricky enough.

kerem referenced this issue

2026-03-07 20:05:11 +03:00

[GH-ISSUE #378] [Discussion] contributes to remark-lint instead #2164

Rows
Columns

[GH-ISSUE #456] Add lint for a link reference without a corresponding link definition (or vice versa) #378

Link Ref without Def

Link Def without Ref