markdownlint 0.25.1 → 0.26.0

package/doc/Rules.md

@@ -13,7 +13,7 @@ Tags: headings, headers
 
 Aliases: heading-increment, header-increment
 
-This rule is triggered when you skip heading levels in a markdown document, for
+This rule is triggered when you skip heading levels in a Markdown document, for
 example:
 
 ```markdown
@@ -331,7 +331,7 @@ Rationale: Indenting by 2 spaces allows the content of a nested list to be in
 line with the start of the content of the parent list when a single space is
 used after the list marker. Indenting by 4 spaces is consistent with code blocks
 and simpler for editors to implement. Additionally, this can be a compatibility
-issue for multi-markdown parsers, which require 4-space indents. More information:
+issue for other Markdown parsers, which require 4-space indents. More information:
 <https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists>
 and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>.
 
@@ -396,7 +396,7 @@ Tags: whitespace, hard_tab
 
 Aliases: no-hard-tabs
 
-Parameters: code_blocks, spaces_per_tab (boolean; default true, number; default 1)
+Parameters: code_blocks, ignore_code_languages, spaces_per_tab (boolean; default true, array of string; default empty, number; default 1)
 
 Fixable: Most violations can be fixed by tooling
 
@@ -429,6 +429,12 @@ set the `code_blocks` parameter to `false`. Code blocks and spans are included
 by default since handling of tabs by Markdown tools can be inconsistent (e.g.,
 using 4 vs. 8 spaces).
 
+When code blocks are scanned (e.g., by default or if `code_blocks` is `true`),
+the `ignore_code_languages` parameter can be set to a list of languages that
+should be ignored (i.e., hard tabs will be allowed, though not required). This
+makes it easier for documents to include code for languages that require hard
+tabs.
+
 By default, violations of this rule are fixed by replacing the tab with 1 space
 character. To use a different number of spaces, set the `spaces_per_tab`
 parameter to the desired value.
@@ -861,7 +867,7 @@ in changelogs):
 ### Features
 ```
 
-Rationale: Some markdown parsers generate anchors for headings based on the
+Rationale: Some Markdown parsers generate anchors for headings based on the
 heading name; headings with the same content can cause problems with that.
 
 <a name="md025"></a>
@@ -1016,7 +1022,7 @@ blockquote symbol at the beginning of the blank line:
 > This is the same blockquote.
 ```
 
-Rationale: Some markdown parsers will treat two blockquotes separated by one
+Rationale: Some Markdown parsers will treat two blockquotes separated by one
 or more blank lines as the same blockquote, while others will treat them as
 separate blockquotes.
 
@@ -1297,13 +1303,13 @@ Aliases: no-inline-html
 
 Parameters: allowed_elements (array of string; default empty)
 
-This rule is triggered whenever raw HTML is used in a markdown document:
+This rule is triggered whenever raw HTML is used in a Markdown document:
 
 ```markdown
 <h1>Inline HTML heading</h1>
 ```
 
-To fix this, use 'pure' markdown instead of including raw HTML:
+To fix this, use 'pure' Markdown instead of including raw HTML:
 
 ```markdown
 # Markdown heading
@@ -1311,9 +1317,9 @@ To fix this, use 'pure' markdown instead of including raw HTML:
 
 Note: To allow specific HTML elements, use the 'allowed_elements' parameter.
 
-Rationale: Raw HTML is allowed in markdown, but this rule is included for
-those who want their documents to only include "pure" markdown, or for those
-who are rendering markdown documents in something other than HTML.
+Rationale: Raw HTML is allowed in Markdown, but this rule is included for
+those who want their documents to only include "pure" Markdown, or for those
+who are rendering Markdown documents into something other than HTML.
 
 <a name="md034"></a>
 
@@ -1339,7 +1345,7 @@ For more information, see <https://www.example.com/>.
 ```
 
 Note: To use a bare URL without it being converted into a link, enclose it in
-a code block, otherwise in some markdown parsers it *will* be converted:
+a code block, otherwise in some Markdown parsers it *will* be converted:
 
 ```markdown
 `https://www.example.com`
@@ -1360,7 +1366,7 @@ The use of quotes around a bare link will *not* trigger this rule, either:
 ```
 
 Rationale: Without angle brackets, the URL isn't converted into a link by many
-markdown parsers.
+Markdown parsers.
 
 <a name="md035"></a>
 
@@ -1429,7 +1435,7 @@ _Another section_
 Consectetur adipiscing elit, sed do eiusmod.
 ```
 
-To fix this, use markdown headings instead of emphasized text to denote
+To fix this, use Markdown headings instead of emphasized text to denote
 sections:
 
 ```markdown
@@ -1752,7 +1758,7 @@ Tags: spelling
 
 Aliases: proper-names
 
-Parameters: names, code_blocks (string array; default `null`, boolean; default `true`)
+Parameters: names, code_blocks, html_elements (string array; default `null`, boolean; default `true`, boolean; default `true`)
 
 Fixable: Most violations can be fixed by tooling
 
@@ -1771,7 +1777,9 @@ the proper capitalization, specify the desired letter case in the `names` array:
 ```
 
 Set the `code_blocks` parameter to `false` to disable this rule for code blocks
-and spans.
+and spans. Set the `html_elements` parameter to `false` to disable this rule
+for HTML elements and attributes (such as when using a proper name as part of
+a path for `a`/`href` or `img`/`src`).
 
 Rationale: Incorrect capitalization of proper names is usually a mistake.
 
@@ -1984,3 +1992,113 @@ The configured strong style can be a specific symbol to use ("asterisk",
 "underscore"), or can require that usage be consistent within the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md051"></a>
+
+## MD051 - Link fragments should be valid
+
+Tags: links
+
+Aliases: link-fragments
+
+This rule is triggered when a link fragment does not correspond to a heading
+in the document:
+
+```markdown
+# Title
+
+[Link](#fragment)
+```
+
+To fix the issue, change the fragment to reference an existing heading:
+
+```markdown
+[Link](#title)
+```
+
+Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a
+valid anchor:
+
+```markdown
+<a id="fragment"></a>
+```
+
+Some platforms (e.g., [GitHub][github-section-links]) automatically create HTML
+anchors for every heading. This makes it easy to link to different sections in
+a document. These internal links can break over time as headings are renamed.
+
+Note: Creating anchors for headings is not part of the CommonMark specification.
+
+[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
+
+<a name="md052"></a>
+
+## MD052 - Reference links and images should use a label that is defined
+
+Tags: images, links
+
+Aliases: reference-links-images
+
+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
+and makes it easy to reuse the same URL in multiple places.
+
+There are three kinds of reference links and images:
+
+```markdown
+Full: [text][label]
+Collapsed: [label][]
+Shortcut: [label]
+
+Full: ![text][image]
+Collapsed: ![image][]
+Shortcut: ![image]
+
+[label]: https://example.com/label
+[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.
+
+> "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.
+
+<a name="md053"></a>
+
+## MD053 - Link and image reference definitions should be needed
+
+Tags: images, links
+
+Aliases: link-image-reference-definitions
+
+Fixable: Most violations can be fixed by tooling
+
+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
+and makes it easy to reuse the same URL in multiple places.
+
+Because link and image reference definitions are located separately from
+where they are used, there are two scenarios where a definition can be
+unnecessary:
+
+1. If a label is not referenced by any link or image in a document, that
+   definition is unused and can be deleted.
+1. If a label is defined multiple times in a document, the first definition is
+   used and the others can be deleted.
+
+This rule considers a reference definition to be used if any link or image
+reference has the corresponding label. "Full", "collapsed", and "shortcut"
+formats are all supported.
+
+<!-- markdownlint-configure-file {
+  "no-inline-html": {
+    "allowed_elements": [
+      "a"
+    ]
+  }
+} -->