Update tests and documentation for MD034/no-bare-urls to explain edge case behavior.

doc-build/md034.md

@@ -19,11 +19,24 @@ Not a clickable link: `https://www.example.com`
 ```
 
 Note: The following scenario does not trigger this rule because it could be a
-valid shortcut link:
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
+
+```markdown
+[text [shortcut] text](https://example.com)
+```
+
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
 Rationale: Without angle brackets, a bare URL or email isn't converted into a
 link by some Markdown parsers.

doc/Rules.md

@@ -1431,12 +1431,25 @@ Not a clickable link: `https://www.example.com`
 ```
 
 Note: The following scenario does not trigger this rule because it could be a
-valid shortcut link:
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
+
+```markdown
+[text [shortcut] text](https://example.com)
+```
+
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
 Rationale: Without angle brackets, a bare URL or email isn't converted into a
 link by some Markdown parsers.
 

doc/md034.md

@@ -27,11 +27,24 @@ Not a clickable link: `https://www.example.com`
 ```
 
 Note: The following scenario does not trigger this rule because it could be a
-valid shortcut link:
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
+
+```markdown
+[text [shortcut] text](https://example.com)
+```
+
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
 Rationale: Without angle brackets, a bare URL or email isn't converted into a
 link by some Markdown parsers.

test/bare-urls.md

@@ -76,3 +76,15 @@ Links with spaces inside angle brackets are okay: [blue jay](<https://en.wikiped
 Email addresses are treated similarly: user@example.com {MD034}
 
 Angle brackets work the same for email: <user@example.com>
+
+---
+
+[is-a-valid]: https://example.com
+
+Links bind to the innermost [link that [is-a-valid] link](https://example.com) {MD034}
+
+But not if the [link [is-not-a-valid] link](https://example.com) {MD034}
+HOWEVER this scenario could have an invalid shortcut and IS reported
+
+Escaping both inner square brackets avoids the unwanted report:
+[link \[is-not-a-valid\] link](https://example.com)

test/snapshots/markdownlint-test-scenarios.js.md

@@ -3164,6 +3164,46 @@ Generated by [AVA](https://avajs.dev).
             'no-bare-urls',
           ],
         },
+        {
+          errorContext: 'https://example.com',
+          errorDetail: null,
+          errorRange: [
+            59,
+            19,
+          ],
+          fixInfo: {
+            deleteCount: 19,
+            editColumn: 59,
+            insertText: '<https://example.com>',
+          },
+          lineNumber: 84,
+          ruleDescription: 'Bare URL used',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md034.md',
+          ruleNames: [
+            'MD034',
+            'no-bare-urls',
+          ],
+        },
+        {
+          errorContext: 'https://example.com',
+          errorDetail: null,
+          errorRange: [
+            45,
+            19,
+          ],
+          fixInfo: {
+            deleteCount: 19,
+            editColumn: 45,
+            insertText: '<https://example.com>',
+          },
+          lineNumber: 86,
+          ruleDescription: 'Bare URL used',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md034.md',
+          ruleNames: [
+            'MD034',
+            'no-bare-urls',
+          ],
+        },
       ],
       fixed: `# Detailed Results Bare URLs␊
       ␊
@@ -3243,6 +3283,18 @@ Generated by [AVA](https://avajs.dev).
       Email addresses are treated similarly: <user@example.com> {MD034}␊
       ␊
       Angle brackets work the same for email: <user@example.com>␊
+      ␊
+      ---␊
+      ␊
+      [is-a-valid]: https://example.com␊
+      ␊
+      Links bind to the innermost [link that [is-a-valid] link](<https://example.com>) {MD034}␊
+      ␊
+      But not if the [link [is-not-a-valid] link](<https://example.com>) {MD034}␊
+      HOWEVER this scenario could have an invalid shortcut and IS reported␊
+      ␊
+      Escaping both inner square brackets avoids the unwanted report:␊
+      [link \\[is-not-a-valid\\] link](https://example.com)␊
       `,
     }