From 83e0ea39f5f4b3a8de00f40c416416d6e93a17e2 Mon Sep 17 00:00:00 2001 From: ChrisBAshton Date: Tue, 23 Mar 2021 15:04:48 +0000 Subject: [PATCH] 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 `foo`. 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: https://github.com/markdownlint/markdownlint/issues/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]: https://github.com/vmg/redcarpet/issues/471 [3]: https://github.com/markdownlint/markdownlint/blob/master/docs/creating_rules.md --- .mdlrc | 1 + mdl/rules.rb | 7 +++++++ source/manual/architecture-deep-dive.html.md | 2 +- source/manual/howto-find-hardcoded-markup-govspeak.html.md | 2 +- 4 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 mdl/rules.rb diff --git a/.mdlrc b/.mdlrc index 20c65af70ce..1001b130747 100644 --- a/.mdlrc +++ b/.mdlrc @@ -1 +1,2 @@ +rulesets ["#{File.dirname(__FILE__)}/mdl/rules.rb"] style "#{File.dirname(__FILE__)}/markdown_lint.rb" diff --git a/mdl/rules.rb b/mdl/rules.rb new file mode 100644 index 00000000000..8bdd4adc460 --- /dev/null +++ b/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 diff --git a/source/manual/architecture-deep-dive.html.md b/source/manual/architecture-deep-dive.html.md index 5872b716596..850d6b11d79 100644 --- a/source/manual/architecture-deep-dive.html.md +++ b/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"]. diff --git a/source/manual/howto-find-hardcoded-markup-govspeak.html.md b/source/manual/howto-find-hardcoded-markup-govspeak.html.md index 5bce4b19c54..32b505bcbd0 100644 --- a/source/manual/howto-find-hardcoded-markup-govspeak.html.md +++ b/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.