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

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)␊
       `,
     }