Update MD054/link-image-style to split reference parameter into full/collapsed/shortcut parameters (fixes #918).

Author: DavidAnson

demo/markdownlint-browser.js

@@ -6633,8 +6633,10 @@ module.exports = {
       config = params.config;
     var autolink = config.autolink === undefined || !!config.autolink;
     var inline = config.inline === undefined || !!config.inline;
-    var reference = config.reference === undefined || !!config.reference;
-    if (autolink && inline && reference) {
+    var full = config.full === undefined || !!config.full;
+    var collapsed = config.collapsed === undefined || !!config.collapsed;
+    var shortcut = config.shortcut === undefined || !!config.shortcut;
+    if (autolink && inline && full && collapsed && shortcut) {
       // Everything allowed, nothing to check
       return;
     }
@@ -6671,11 +6673,15 @@ module.exports = {
             // link kind is an inline link
             isError = !inline;
           } else {
-            // link kind is a reference link
-            var referenceLabel = getTokenTextByType(descendents, "referenceString") || label;
-            var definition = definitions.get(referenceLabel);
+            // link kind is a full/collapsed/shortcut reference link
+            var isShortcut = !children.some(function (t) {
+              return t.type === "reference";
+            });
+            var referenceString = getTokenTextByType(descendents, "referenceString");
+            var isCollapsed = referenceString === null;
+            var definition = definitions.get(referenceString || label);
             destination = definition && definition[1];
-            isError = !reference && destination;
+            isError = destination && (isShortcut ? !shortcut : isCollapsed ? !collapsed : !full);
           }
         }
         if (isError) {

doc-build/md054.md

@@ -1,10 +1,9 @@
 Links and images in Markdown can provide the link destination or image source at
 the time of use or can use a label to reference a definition elsewhere in the
-document. The reference format is convenient for keeping paragraph text
-clutter-free and makes it easy to reuse the same URL in multiple places.
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
 
-By default, this rule allows all link/image styles. It is possible to disable
-one or more of those styles.
+By default, this rule allows all link/image styles.
 
 Setting the `autolink` parameter to `false` disables autolinks:
 
@@ -20,20 +19,34 @@ Setting the `inline` parameter to `false` disables inline links and images:
 ![image](https://example.com)
 ```
 
-Setting the `reference` parameter to `false` disables full, collapsed, and
-shortcut reference links and images:
+Setting the `full` parameter to `false` disables full reference links and
+images:
 
 ```markdown
 [link][url]
 
-[url][]
+![image][url]
 
-[url]
+[url]: https://example.com
+```
 
-![image][url]
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
 
 ![url][]
 
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
 ![url]
 
 [url]: https://example.com
@@ -43,12 +56,12 @@ To fix violations of this rule, change the link or image to use an allowed
 style. This rule can automatically fix violations when a link or image can be
 converted to the `inline` style (preferred) or a link can be converted to the
 `autolink` style (which does not support images and must be an absolute URL).
-This rule does not fix scenarios that require converting a link or image to the
-`reference` style because that involves naming the reference and knowing where
-in the document to insert it.
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
 Autolinks are concise, but appear as URLs which can be long and confusing.
 Inline links and images can include descriptive text, but take up more space in
 Markdown form. Reference links and images can be easier to read and manipulate
-in Markdown form, but require editing two locations.
+in Markdown form, but require a separate link reference definition.

doc/Rules.md

@@ -2234,18 +2234,21 @@ Aliases: `link-image-style`
 Parameters:
 
 - `autolink`: Allow autolinks (`boolean`, default `true`)
+- `collapsed`: Allow collapsed reference links and images (`boolean`, default
+  `true`)
+- `full`: Allow full reference links and images (`boolean`, default `true`)
 - `inline`: Allow inline links and images (`boolean`, default `true`)
-- `reference`: Allow reference links and images (`boolean`, default `true`)
+- `shortcut`: Allow shortcut reference links and images (`boolean`, default
+  `true`)
 
 Fixable: Some violations can be fixed by tooling
 
 Links and images in Markdown can provide the link destination or image source at
 the time of use or can use a label to reference a definition elsewhere in the
-document. The reference format is convenient for keeping paragraph text
-clutter-free and makes it easy to reuse the same URL in multiple places.
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
 
-By default, this rule allows all link/image styles. It is possible to disable
-one or more of those styles.
+By default, this rule allows all link/image styles.
 
 Setting the `autolink` parameter to `false` disables autolinks:
 
@@ -2261,20 +2264,34 @@ Setting the `inline` parameter to `false` disables inline links and images:
 ![image](https://example.com)
 ```
 
-Setting the `reference` parameter to `false` disables full, collapsed, and
-shortcut reference links and images:
+Setting the `full` parameter to `false` disables full reference links and
+images:
 
 ```markdown
 [link][url]
 
-[url][]
+![image][url]
 
-[url]
+[url]: https://example.com
+```
 
-![image][url]
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
 
 ![url][]
 
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
 ![url]
 
 [url]: https://example.com
@@ -2284,15 +2301,15 @@ To fix violations of this rule, change the link or image to use an allowed
 style. This rule can automatically fix violations when a link or image can be
 converted to the `inline` style (preferred) or a link can be converted to the
 `autolink` style (which does not support images and must be an absolute URL).
-This rule does not fix scenarios that require converting a link or image to the
-`reference` style because that involves naming the reference and knowing where
-in the document to insert it.
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
 Autolinks are concise, but appear as URLs which can be long and confusing.
 Inline links and images can include descriptive text, but take up more space in
 Markdown form. Reference links and images can be easier to read and manipulate
-in Markdown form, but require editing two locations.
+in Markdown form, but require a separate link reference definition.
 
 <!-- markdownlint-configure-file {
   "no-inline-html": {

doc/md054.md

@@ -7,18 +7,21 @@ Aliases: `link-image-style`
 Parameters:
 
 - `autolink`: Allow autolinks (`boolean`, default `true`)
+- `collapsed`: Allow collapsed reference links and images (`boolean`, default
+  `true`)
+- `full`: Allow full reference links and images (`boolean`, default `true`)
 - `inline`: Allow inline links and images (`boolean`, default `true`)
-- `reference`: Allow reference links and images (`boolean`, default `true`)
+- `shortcut`: Allow shortcut reference links and images (`boolean`, default
+  `true`)
 
 Fixable: Some violations can be fixed by tooling
 
 Links and images in Markdown can provide the link destination or image source at
 the time of use or can use a label to reference a definition elsewhere in the
-document. The reference format is convenient for keeping paragraph text
-clutter-free and makes it easy to reuse the same URL in multiple places.
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
 
-By default, this rule allows all link/image styles. It is possible to disable
-one or more of those styles.
+By default, this rule allows all link/image styles.
 
 Setting the `autolink` parameter to `false` disables autolinks:
 
@@ -34,20 +37,34 @@ Setting the `inline` parameter to `false` disables inline links and images:
 ![image](https://example.com)
 ```
 
-Setting the `reference` parameter to `false` disables full, collapsed, and
-shortcut reference links and images:
+Setting the `full` parameter to `false` disables full reference links and
+images:
 
 ```markdown
 [link][url]
 
-[url][]
+![image][url]
 
-[url]
+[url]: https://example.com
+```
 
-![image][url]
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
 
 ![url][]
 
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
 ![url]
 
 [url]: https://example.com
@@ -57,12 +74,12 @@ To fix violations of this rule, change the link or image to use an allowed
 style. This rule can automatically fix violations when a link or image can be
 converted to the `inline` style (preferred) or a link can be converted to the
 `autolink` style (which does not support images and must be an absolute URL).
-This rule does not fix scenarios that require converting a link or image to the
-`reference` style because that involves naming the reference and knowing where
-in the document to insert it.
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
 Autolinks are concise, but appear as URLs which can be long and confusing.
 Inline links and images can include descriptive text, but take up more space in
 Markdown form. Reference links and images can be easier to read and manipulate
-in Markdown form, but require editing two locations.
+in Markdown form, but require a separate link reference definition.

lib/configuration.d.ts

@@ -1009,9 +1009,17 @@ export interface Configuration {
          */
         inline?: boolean;
         /**
-         * Allow reference links and images
+         * Allow full reference links and images
          */
-        reference?: boolean;
+        full?: boolean;
+        /**
+         * Allow collapsed reference links and images
+         */
+        collapsed?: boolean;
+        /**
+         * Allow shortcut reference links and images
+         */
+        shortcut?: boolean;
       };
   /**
    * MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md054.md
@@ -1028,9 +1036,17 @@ export interface Configuration {
          */
         inline?: boolean;
         /**
-         * Allow reference links and images
+         * Allow full reference links and images
+         */
+        full?: boolean;
+        /**
+         * Allow collapsed reference links and images
+         */
+        collapsed?: boolean;
+        /**
+         * Allow shortcut reference links and images
          */
-        reference?: boolean;
+        shortcut?: boolean;
       };
   /**
    * headings : MD001, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043

lib/md054.js

@@ -29,8 +29,10 @@ module.exports = {
     const { parsers, config } = params;
     const autolink = (config.autolink === undefined) || !!config.autolink;
     const inline = (config.inline === undefined) || !!config.inline;
-    const reference = (config.reference === undefined) || !!config.reference;
-    if (autolink && inline && reference) {
+    const full = (config.full === undefined) || !!config.full;
+    const collapsed = (config.collapsed === undefined) || !!config.collapsed;
+    const shortcut = (config.shortcut === undefined) || !!config.shortcut;
+    if (autolink && inline && full && collapsed && shortcut) {
       // Everything allowed, nothing to check
       return;
     }
@@ -62,12 +64,14 @@ module.exports = {
           // link kind is an inline link
           isError = !inline;
         } else {
-          // link kind is a reference link
-          const referenceLabel =
-            getTokenTextByType(descendents, "referenceString") || label;
-          const definition = definitions.get(referenceLabel);
+          // link kind is a full/collapsed/shortcut reference link
+          const isShortcut = !children.some((t) => t.type === "reference");
+          const referenceString = getTokenTextByType(descendents, "referenceString");
+          const isCollapsed = (referenceString === null);
+          const definition = definitions.get(referenceString || label);
           destination = definition && definition[1];
-          isError = !reference && destination;
+          isError = destination &&
+            (isShortcut ? !shortcut : (isCollapsed ? !collapsed : !full));
         }
       }
       if (isError) {

schema/.markdownlint.jsonc

@@ -285,7 +285,11 @@
     "autolink": true,
     // Allow inline links and images
     "inline": true,
-    // Allow reference links and images
-    "reference": true
+    // Allow full reference links and images
+    "full": true,
+    // Allow collapsed reference links and images
+    "collapsed": true,
+    // Allow shortcut reference links and images
+    "shortcut": true
   }
 }

schema/.markdownlint.yaml

@@ -256,5 +256,9 @@ MD054:
   autolink: true
   # Allow inline links and images
   inline: true
-  # Allow reference links and images
-  reference: true
+  # Allow full reference links and images
+  full: true
+  # Allow collapsed reference links and images
+  collapsed: true
+  # Allow shortcut reference links and images
+  shortcut: true

schema/build-config-schema.js

@@ -509,8 +509,18 @@ for (const rule of rules) {
           "type": "boolean",
           "default": true
         },
-        "reference": {
-          "description": "Allow reference links and images",
+        "full": {
+          "description": "Allow full reference links and images",
+          "type": "boolean",
+          "default": true
+        },
+        "collapsed": {
+          "description": "Allow collapsed reference links and images",
+          "type": "boolean",
+          "default": true
+        },
+        "shortcut": {
+          "description": "Allow shortcut reference links and images",
           "type": "boolean",
           "default": true
         }