Refactor new MD054/link-image-style rule, add tests, update documentation (fixes #40, fixes #399).

doc-build/md054.md

@@ -1,11 +1,54 @@
-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 latter reference format is convenient for keeping paragraph
-text clutter-free and makes it easy to reuse the same URL in multiple places.
+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.
 
-This rule can be used to enforce a link or image style for the document that:
+By default, this rule allows all link/image styles. It is possible to disable
+one or more of those styles.
 
-- `inline`: provides the link destination or image source at the time of use
-- `reference`: defines the link destination or image source elsewhere to be
-  referenced by label
-- or `consistent`: Requires the same style be used everywhere in the document
+Setting the `autolink` parameter to `false` disables autolinks:
+
+```markdown
+<https://example.com>
+```
+
+Setting the `inline` parameter to `false` disables inline links and images:
+
+```markdown
+[link](https://example.com)
+
+![image](https://example.com)
+```
+
+Setting the `reference` parameter to `false` disables full, collapsed, and
+shortcut reference links and images:
+
+```markdown
+[link][url]
+
+[url][]
+
+[url]
+
+![image][url]
+
+![url][]
+
+![url]
+
+[url]: https://example.com
+```
+
+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.
+
+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.