markdownlint 0.29.0 → 0.31.0

package/doc/CustomRules.md

@@ -82,6 +82,8 @@ properties:
       error.
     - `context` is an optional `String` with relevant text surrounding the error
       location.
+    - `information` is an optional (absolute) `URL` of a link to override the
+      same-named value provided by the rule definition. (Uncommon)
     - `range` is an optional `Array` with two `Number` values identifying the
       1-based column and length of the error.
     - `fixInfo` is an optional `Object` with information about how to fix the

package/doc/Rules.md

@@ -806,8 +806,8 @@ Aliases: `blanks-around-headers`, `blanks-around-headings`
 
 Parameters:
 
-- `lines_above`: Blank lines above heading (`integer`, default `1`)
-- `lines_below`: Blank lines below heading (`integer`, default `1`)
+- `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
+- `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -836,10 +836,16 @@ Some more text
 ```
 
 The `lines_above` and `lines_below` parameters can be used to specify a
-different number of blank lines (including 0) above or below each heading.
+different number of blank lines (including `0`) above or below each heading.
+If the value `-1` is used for either parameter, any number of blank lines is
+allowed. To customize the number of lines above or below each heading level
+individually, specify a `number[]` where values correspond to heading levels
+1-6 (in order).
 
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+Notes: If `lines_above` or `lines_below` are configured to require more than one
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
+rule checks for *at least* as many blank lines as specified; any extra blank
+lines are ignored.
 
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them
@@ -986,8 +992,7 @@ Aliases: `no-trailing-punctuation`
 
 Parameters:
 
-- `punctuation`: Punctuation characters not allowed at end of headings
-  (`string`, default `.,;:!。，；：！`)
+- `punctuation`: Punctuation characters (`string`, default `.,;:!。，；：！`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2079,8 +2084,8 @@ Aliases: `emphasis-style`
 
 Parameters:
 
-- `style`: Emphasis style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Emphasis style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2114,8 +2119,8 @@ Aliases: `strong-style`
 
 Parameters:
 
-- `style`: Strong style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Strong style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2153,21 +2158,32 @@ This rule is triggered when a link fragment does not match any of the fragments
 that are automatically generated for headings in a document:
 
 ```markdown
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# Heading Name
+
+[Link](#heading-name)
+```
+
+Alternatively, some platforms allow the syntax `{#named-anchor}` to be used
+within a heading to provide a specific name (consisting of only lower-case
+letters, numbers, `-`, and `_`):
 
-[Link](#title)
+```markdown
+# Heading Name {#custom-name}
+
+[Link](#custom-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>
@@ -2200,6 +2216,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -2220,13 +2240,16 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.
 
 <a name="md053"></a>
 

package/doc/md022.md

@@ -6,8 +6,8 @@ Aliases: `blanks-around-headers`, `blanks-around-headings`
 
 Parameters:
 
-- `lines_above`: Blank lines above heading (`integer`, default `1`)
-- `lines_below`: Blank lines below heading (`integer`, default `1`)
+- `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
+- `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -36,10 +36,16 @@ Some more text
 ```
 
 The `lines_above` and `lines_below` parameters can be used to specify a
-different number of blank lines (including 0) above or below each heading.
-
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+different number of blank lines (including `0`) above or below each heading.
+If the value `-1` is used for either parameter, any number of blank lines is
+allowed. To customize the number of lines above or below each heading level
+individually, specify a `number[]` where values correspond to heading levels
+1-6 (in order).
+
+Notes: If `lines_above` or `lines_below` are configured to require more than one
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
+rule checks for *at least* as many blank lines as specified; any extra blank
+lines are ignored.
 
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them

package/doc/md026.md

@@ -6,8 +6,7 @@ Aliases: `no-trailing-punctuation`
 
 Parameters:
 
-- `punctuation`: Punctuation characters not allowed at end of headings
-  (`string`, default `.,;:!。，；：！`)
+- `punctuation`: Punctuation characters (`string`, default `.,;:!。，；：！`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md049.md

@@ -6,8 +6,8 @@ Aliases: `emphasis-style`
 
 Parameters:
 
-- `style`: Emphasis style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Emphasis style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md050.md

@@ -6,8 +6,8 @@ Aliases: `strong-style`
 
 Parameters:
 
-- `style`: Strong style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Strong style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md051.md

@@ -10,21 +10,32 @@ This rule is triggered when a link fragment does not match any of the fragments
 that are automatically generated for headings in a document:
 
 ```markdown
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# Heading Name
 
-[Link](#title)
+[Link](#heading-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, some platforms allow the syntax `{#named-anchor}` to be used
+within a heading to provide a specific name (consisting of only lower-case
+letters, numbers, `-`, and `_`):
+
+```markdown
+# Heading Name {#custom-name}
+
+[Link](#custom-name)
+```
+
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

package/doc/md052.md

@@ -4,6 +4,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -24,10 +28,13 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.