diff --git a/demo/markdownlint-browser.js b/demo/markdownlint-browser.js index c049a0d14..fa20c1cf1 100644 --- a/demo/markdownlint-browser.js +++ b/demo/markdownlint-browser.js @@ -3658,7 +3658,7 @@ module.exports = { if (!linkDestinationRe.test(prefix)) { const unescaped = unescapeMarkdown(prefix + "<", "_"); if (!unescaped.endsWith("_")) { - addError(onError, lineIndex + 1, "Element: " + element, null, [match.index + 1, tag.length]); + addError(onError, lineIndex + 1, "Element: " + element, undefined, [match.index + 1, tag.length]); } } } @@ -4727,7 +4727,8 @@ module.exports = { "description": "Link and image reference definitions should be needed", "tags": ["images", "links"], "function": function MD053(params, onError) { - const { lines } = params; + const ignored = new Set(params.config.ignored_definitions || ["//"]); + const lines = params.lines; const { references, shortcuts, definitions, duplicateDefinitions } = referenceLinkImageData(); const singleLineDefinition = (line) => (line.replace(linkReferenceDefinitionRe, "").trim().length > 0); const deleteFixInfo = { @@ -4736,7 +4737,9 @@ module.exports = { // Look for unused link references (unreferenced by any link/image) for (const definition of definitions.entries()) { const [label, lineIndex] = definition; - if (!references.has(label) && !shortcuts.has(label)) { + if (!ignored.has(label) && + !references.has(label) && + !shortcuts.has(label)) { const line = lines[lineIndex]; addError(onError, lineIndex + 1, `Unused link or image reference definition: "${label}"`, ellipsify(line), [1, line.length], singleLineDefinition(line) ? deleteFixInfo : 0); } @@ -4744,8 +4747,10 @@ module.exports = { // Look for duplicate link references (defined more than once) for (const duplicateDefinition of duplicateDefinitions) { const [label, lineIndex] = duplicateDefinition; - const line = lines[lineIndex]; - addError(onError, lineIndex + 1, `Duplicate link or image reference definition: "${label}"`, ellipsify(line), [1, line.length], singleLineDefinition(line) ? deleteFixInfo : 0); + if (!ignored.has(label)) { + const line = lines[lineIndex]; + addError(onError, lineIndex + 1, `Duplicate link or image reference definition: "${label}"`, ellipsify(line), [1, line.length], singleLineDefinition(line) ? deleteFixInfo : 0); + } } } }; diff --git a/doc/Rules.md b/doc/Rules.md index d5170944e..7a2debbb7 100644 --- a/doc/Rules.md +++ b/doc/Rules.md @@ -1315,7 +1315,7 @@ To fix this, use 'pure' Markdown instead of including raw HTML: # Markdown heading ``` -Note: To allow specific HTML elements, use the 'allowed_elements' parameter. +Note: To allow specific HTML elements, use the `allowed_elements` parameter. Rationale: Raw HTML is allowed in Markdown, but this rule is included for those who want their documents to only include "pure" Markdown, or for those @@ -2075,6 +2075,8 @@ Tags: images, links Aliases: link-image-reference-definitions +Parameters: ignored_definitions (array of string; default [ "//" ]) + Fixable: Most violations can be fixed by tooling Links and images in Markdown can provide the link destination or image source @@ -2092,9 +2094,18 @@ unnecessary: used and the others can be deleted. This rule considers a reference definition to be used if any link or image -reference has the corresponding label. "Full", "collapsed", and "shortcut" +reference has the corresponding label. The "full", "collapsed", and "shortcut" formats are all supported. +If there are reference definitions that are deliberately unreferenced, they can +be ignored by setting the `ignored_definitions` parameter. The default value of +this parameter ignores the following convention for adding non-HTML comments to +Markdown: + +```md +[//]: # (This behaves like a comment) +``` + diff --git a/test/reference-links-ignored-definitions.md b/test/reference-links-ignored-definitions.md new file mode 100644 index 000000000..ef063faf0 --- /dev/null +++ b/test/reference-links-ignored-definitions.md @@ -0,0 +1,17 @@ +# Reference Links Ignored Definitions + +Used reference link: [label] + +[label]: https://example.com/label +[oops]: https://example.com/{MD053} +[okay]: https://example.com/ignored +[yep]: https://example.com/ignored + + diff --git a/test/snapshots/markdownlint-test-scenarios.js.md b/test/snapshots/markdownlint-test-scenarios.js.md index 4a88ad578..bc568e450 100644 --- a/test/snapshots/markdownlint-test-scenarios.js.md +++ b/test/snapshots/markdownlint-test-scenarios.js.md @@ -33768,7 +33768,7 @@ Generated by [AVA](https://avajs.dev). 25, ], fixInfo: null, - lineNumber: 196, + lineNumber: 202, ruleDescription: 'Reference links and images should use a label that is defined', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md052', ruleNames: [ @@ -33784,7 +33784,7 @@ Generated by [AVA](https://avajs.dev). 10, ], fixInfo: null, - lineNumber: 210, + lineNumber: 216, ruleDescription: 'Reference links and images should use a label that is defined', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md052', ruleNames: [ @@ -33802,7 +33802,7 @@ Generated by [AVA](https://avajs.dev). fixInfo: { deleteCount: -1, }, - lineNumber: 172, + lineNumber: 178, ruleDescription: 'Link and image reference definitions should be needed', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', ruleNames: [ @@ -33820,7 +33820,7 @@ Generated by [AVA](https://avajs.dev). fixInfo: { deleteCount: -1, }, - lineNumber: 175, + lineNumber: 181, ruleDescription: 'Link and image reference definitions should be needed', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', ruleNames: [ @@ -33838,7 +33838,7 @@ Generated by [AVA](https://avajs.dev). fixInfo: { deleteCount: -1, }, - lineNumber: 178, + lineNumber: 184, ruleDescription: 'Link and image reference definitions should be needed', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', ruleNames: [ @@ -33854,7 +33854,7 @@ Generated by [AVA](https://avajs.dev). 44, ], fixInfo: null, - lineNumber: 180, + lineNumber: 186, ruleDescription: 'Link and image reference definitions should be needed', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', ruleNames: [ @@ -33870,7 +33870,7 @@ Generated by [AVA](https://avajs.dev). 44, ], fixInfo: null, - lineNumber: 183, + lineNumber: 189, ruleDescription: 'Link and image reference definitions should be needed', ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', ruleNames: [ @@ -34047,6 +34047,12 @@ Generated by [AVA](https://avajs.dev). [unique6]: https://example.com/unique6␊ [unique7]: https://example.com/unique7␊ ␊ + ## Ignored Labels␊ + ␊ + [//]: # (This is a technique for putting comments in Markdown)␊ + ␊ + [//]: <> (Here is another variant)␊ + ␊ ## Invalid Labels␊ ␊ Duplicate:␊ @@ -34089,6 +34095,107 @@ Generated by [AVA](https://avajs.dev). `, } +## reference-links-ignored-definitions-empty.md + +> Snapshot 1 + + { + errors: [ + { + errorContext: '[oops]: https://example.com/{M...', + errorDetail: 'Unused link or image reference definition: "oops"', + errorRange: [ + 1, + 35, + ], + fixInfo: { + deleteCount: -1, + }, + lineNumber: 6, + ruleDescription: 'Link and image reference definitions should be needed', + ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', + ruleNames: [ + 'MD053', + 'link-image-reference-definitions', + ], + }, + { + errorContext: '[//]: <> ({MD053})', + errorDetail: 'Unused link or image reference definition: "//"', + errorRange: [ + 1, + 18, + ], + fixInfo: { + deleteCount: -1, + }, + lineNumber: 7, + ruleDescription: 'Link and image reference definitions should be needed', + ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', + ruleNames: [ + 'MD053', + 'link-image-reference-definitions', + ], + }, + ], + fixed: `# Reference Links Ignored Definitions (Empty)␊ + ␊ + Used reference link: [label]␊ + ␊ + [label]: https://example.com/label␊ + ␊ + ␊ + `, + } + +## reference-links-ignored-definitions.md + +> Snapshot 1 + + { + errors: [ + { + errorContext: '[oops]: https://example.com/{M...', + errorDetail: 'Unused link or image reference definition: "oops"', + errorRange: [ + 1, + 35, + ], + fixInfo: { + deleteCount: -1, + }, + lineNumber: 6, + ruleDescription: 'Link and image reference definitions should be needed', + ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md053', + ruleNames: [ + 'MD053', + 'link-image-reference-definitions', + ], + }, + ], + fixed: `# Reference Links Ignored Definitions␊ + ␊ + Used reference link: [label]␊ + ␊ + [label]: https://example.com/label␊ + [okay]: https://example.com/ignored␊ + [yep]: https://example.com/ignored␊ + ␊ + ␊ + `, + } + ## required-headings-all-optional-at-least-one.md > Snapshot 1 diff --git a/test/snapshots/markdownlint-test-scenarios.js.snap b/test/snapshots/markdownlint-test-scenarios.js.snap index 86a8ffb34..0174966e2 100644 Binary files a/test/snapshots/markdownlint-test-scenarios.js.snap and b/test/snapshots/markdownlint-test-scenarios.js.snap differ