Add markdown lint rule to prevent shortcut reference link bug

Redcarpet has an issue whereby shortcut reference links [1] followed
by parentheses are incorrectly parsed. [2]

```
[foo] (bar)
[foo: http://example.com
```

...would be parsed as `<a href="bar">foo</a>`. Screenshot of the issue:

![](https://user-images.githubusercontent.com/5111927/112168271-0dcb4c00-8be9-11eb-9235-026c68af1019.png)

We initially worked around the issue by swapping out the markdown
library Redcarpet for Markdown, but this has meant we're missing
out on accessibility improvements built into tech_docs_gem, so we
needed a new approach.

This new linting rule - which is called as part of the lint_markdown
rake task, and fails the build if occurrences are found - detects
shortcut reference links followed by parentheses. It suggests a
fix of converting these to collapsed reference links by appending
`[]`, which removes any ambiguity for the parser. Example output:

```
source/manual/howto-find-hardcoded-markup-govspeak.html.md:12: no-parentheses-after-shortcut-reference-link No parentheses allowed after shortcut reference link (use collapsed reference link instead, e.g. `[foo]` => `[foo][]`)
source/manual/architecture-deep-dive.html.md:248: no-parentheses-after-shortcut-reference-link No parentheses allowed after shortcut reference link (use collapsed reference link instead, e.g. `[foo]` => `[foo][]`)
```

This rule is an implementation of a suggestion I made to the open
source project in September 2020:
markdownlint/markdownlint#351

It uses a custom rule code `MY001`, as suggested in the docs. [3]

Finally, I fixed up the two instances which this rule found in the
repo. Future instances should be prevented from being added, via
the CI process.

[1]: https://github.github.com/gfm/#shortcut-reference-link
[2]: vmg/redcarpet#471
[3]: https://github.com/markdownlint/markdownlint/blob/master/docs/creating_rules.md

.mdlrc

@@ -1 +1,2 @@
+rulesets ["#{File.dirname(__FILE__)}/mdl/rules.rb"]
 style "#{File.dirname(__FILE__)}/markdown_lint.rb"

mdl/rules.rb

@@ -0,0 +1,7 @@
+rule "MY001", "No parentheses allowed after shortcut reference link (use collapsed reference link instead, e.g. `[foo]` => `[foo][]`)" do
+  aliases "no-parentheses-after-shortcut-reference-link"
+  check do |doc|
+    # matches `[foo] (bar)`, doesn't match `[foo][baz] (bar)`
+    doc.matching_lines(/ \[[^\]]+\] \(/)
+  end
+end

source/manual/architecture-deep-dive.html.md

@@ -246,7 +246,7 @@ of 'router'. You can swap `www` for `draft-origin` to view the draft stack at
 origin. The draft stack is not IP-restricted, as we need to be able to share
 links to be reviewed ("2i'd") or fact-checked by non-Government departments.
 It is, however, only visible to users who have been verified through
-Authenticating Proxy, by signing into [signon] (an authentication and
+Authenticating Proxy, by signing into [signon][] (an authentication and
 authorisation portal) or by providing a valid `auth_bypass_id` (as a URI
 parameter or session cookie). Read more about previews in ["How the draft stack works"].
 

source/manual/howto-find-hardcoded-markup-govspeak.html.md

@@ -10,7 +10,7 @@ Usually to find usage of markup we can look in our source code.
 
 For example if we wanted to see which templates use a class called 'button' you could search in GitHub.
 
-However [GovSpeak] (our variant of Markdown) includes markup such as buttons that will be in published content.
+However [GovSpeak][] (our variant of Markdown) includes markup such as buttons that will be in published content.
 
 So, with this in mind you'll need to search all published content.