markdownlint 0.12.0 → 0.14.2

package/doc/Rules.md

@@ -51,20 +51,24 @@ Aliases: first-heading-h1, first-header-h1
 
 Parameters: level (number; default 1)
 
-This rule is triggered when the first heading in the document isn't a h1 heading:
+> Note: *MD002 has been deprecated and is disabled by default.*
+> [MD041/first-line-heading](#md041) offers an improved implementation.
+
+This rule is intended to ensure document headings start at the top level and
+is triggered when the first heading in the document isn't an h1 heading:
 
 ```markdown
-## This isn't a H1 heading
+## This isn't an H1 heading
 
 ### Another heading
 ```
 
-The first heading in the document should be a h1 heading:
+The first heading in the document should be an h1 heading:
 
 ```markdown
-# Start with a H1 heading
+# Start with an H1 heading
 
-## Then use a H2 for subsections
+## Then use an H2 for subsections
 ```
 
 Note: The `level` parameter can be used to change the top level (ex: to h2) in
@@ -215,7 +219,6 @@ the same ending column:
 ...
 ```
 
-
 <a name="md006"></a>
 
 ## MD006 - Consider starting bulleted lists at the beginning of the line
@@ -294,7 +297,7 @@ when a single space is used after the list marker.
 
 Rationale (4 space indent): Same indent as code blocks, simpler for editors to
 implement. See
-<http://www.cirosantilli.com/markdown-styleguide/#indented-lists> for more
+<https://www.cirosantilli.com/markdown-style-guide/#indentation-of-content-inside-lists> for more
 information.
 
 In addition, this is a compatibility issue with multi-markdown parsers, which
@@ -383,13 +386,13 @@ where the syntax appears to have been reversed (the `[]` and `()` are
 reversed):
 
 ```markdown
-(Incorrect link syntax)[http://www.example.com/]
+(Incorrect link syntax)[https://www.example.com/]
 ```
 
 To fix this, swap the `[]` and `()` around:
 
 ```markdown
-[Correct link syntax](http://www.example.com/)
+[Correct link syntax](https://www.example.com/)
 ```
 
 Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style footnotes do not trigger this rule:
@@ -440,13 +443,14 @@ Tags: line_length
 
 Aliases: line-length
 
-Parameters: line_length, code_blocks, tables, headings, headers (number; default 80, boolean; default true)
+Parameters: line_length, heading_line_length, code_blocks, tables, headings, headers (number; default 80, boolean; default true)
 
 > If `headings` is not provided, `headers` (deprecated) will be used.
 
 This rule is triggered when there are lines that are longer than the
-configured line length (default: 80 characters). To fix this, split the line
-up into multiple lines.
+configured `line_length` (default: 80 characters). To fix this, split the line
+up into multiple lines. To set a different maximum length for headings, use
+`heading_line_length`.
 
 This rule has an exception where there is no whitespace beyond the configured
 line length. This allows you to still include items such as long URLs without
@@ -499,7 +503,7 @@ baz
 
 Rationale: it is easier to copy and paste and less noisy if the dollar signs
 are omitted when they are not needed. See
-<http://www.cirosantilli.com/markdown-styleguide/#dollar-signs-in-shell-code>
+<https://www.cirosantilli.com/markdown-style-guide/#dollar-signs-in-shell-code>
 for more information.
 
 <a name="md018"></a>
@@ -619,8 +623,10 @@ Tags: headings, headers, blank_lines
 
 Aliases: blanks-around-headings, blanks-around-headers
 
+Parameters: lines_above, lines_below (number; default 1)
+
 This rule is triggered when headings (any style) are either not preceded or not
-followed by a blank line:
+followed by at least one blank line:
 
 ```markdown
 # Heading 1
@@ -647,6 +653,12 @@ 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 as
 regular 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) should also be customized.
+
 <a name="md023"></a>
 
 ## MD023 - Headings must start at the beginning of the line
@@ -727,12 +739,12 @@ in change logs):
 
 Tags: headings, headers
 
-Aliases: single-h1
+Aliases: single-title, single-h1
 
-Parameters: level (number; default 1)
+Parameters: level, front_matter_title (number; default 1, string; default "^\s*title:")
 
 This rule is triggered when a top level heading is in use (the first line of
-the file is a h1 heading), and more than one h1 heading is in use in the
+the file is an h1 heading), and more than one h1 heading is in use in the
 document:
 
 ```markdown
@@ -753,7 +765,7 @@ headings:
 ## Another heading
 ```
 
-Rationale: A top level heading is a h1 on the first line of the file, and
+Rationale: A top level heading is an h1 on the first line of the file, and
 serves as the title for the document. If this convention is in use, then there
 can not be more than one title for the document, and the entire document
 should be contained within this heading.
@@ -761,6 +773,13 @@ should be contained within this heading.
 Note: The `level` parameter can be used to change the top level (ex: to h2) in
 cases where an h1 is added externally.
 
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains
+a `title` property (commonly used with blog posts), this rule treats that as a top
+level heading and will report a violation for any subsequent top level headings.
+To use a different property name in front matter, specify the text of a regular
+expression via the `front_matter_title` parameter. To disable the use of front
+matter by this rule, specify `""` for `front_matter_title`.
+
 <a name="md026"></a>
 
 ## MD026 - Trailing punctuation in heading
@@ -863,11 +882,12 @@ Tags: ol
 
 Aliases: ol-prefix
 
-Parameters: style ("one", "ordered", "one_or_ordered"; default "one_or_ordered")
+Parameters: style ("one", "ordered", "one_or_ordered", "zero"; default "one_or_ordered")
 
-This rule is triggered on ordered lists that do not either start with '1.' or
+This rule is triggered for ordered lists that do not either start with '1.' or
 do not have a prefix that increases in numerical order (depending on the
-configured style).
+configured style). The less-common pattern of using '0.' for all prefixes is
+also supported.
 
 Example valid list if the style is configured as 'one':
 
@@ -887,6 +907,14 @@ Example valid list if the style is configured as 'ordered':
 
 Both examples are valid when the style is configured as 'one_or_ordered'.
 
+Example valid list if the style is configured as 'zero':
+
+```markdown
+0. Do this.
+0. Do that.
+0. Done.
+```
+
 Example invalid list for all styles:
 
 ```markdown
@@ -941,7 +969,7 @@ of every item in the list consists of a single paragraph, or multiple
 paragraphs (including sub-lists and code blocks).
 
 For example, the style guide at
-<http://www.cirosantilli.com/markdown-styleguide/#spaces-after-marker>
+<https://www.cirosantilli.com/markdown-style-guide/#spaces-after-list-marker>
 specifies that 1 space after the list marker should be used if every item in
 the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
 and unordered lists respectively) if there are multiple paragraphs of content
@@ -1109,13 +1137,13 @@ This rule is triggered whenever a URL is given that isn't surrounded by angle
 brackets:
 
 ```markdown
-For more information, see http://www.example.com/.
+For more information, see https://www.example.com/.
 ```
 
 To fix this, add angle brackets around the URL:
 
 ```markdown
-For more information, see <http://www.example.com/>.
+For more information, see <https://www.example.com/>.
 ```
 
 Rationale: Without angle brackets, the URL isn't converted into a link in many
@@ -1126,7 +1154,7 @@ enclose it in a code block, otherwise in some markdown parsers it _will_ be
 converted:
 
 ```markdown
-`http://www.example.com`
+`https://www.example.com`
 ```
 
 <a name="md035"></a>
@@ -1294,13 +1322,13 @@ Aliases: no-space-in-links
 This rule is triggered on links that have spaces surrounding the link text:
 
 ```markdown
-[ a link ](http://www.example.com/)
+[ a link ](https://www.example.com/)
 ```
 
 To fix this, remove the spaces surrounding the link text:
 
 ```markdown
-[a link](http://www.example.com/)
+[a link](https://www.example.com/)
 ```
 
 <a name="md040"></a>
@@ -1336,18 +1364,18 @@ echo Hello world
 
 Tags: headings, headers
 
-Aliases: first-line-h1
+Aliases: first-line-heading, first-line-h1
 
 Parameters: level, front_matter_title (number; default 1, string; default "^\s*title:")
 
-This rule is triggered when the first line in the file isn't a top level (h1)
-heading:
+This rule is intended to ensure documents have a title and is triggered when
+the first line in the file isn't a top level (h1) heading:
 
 ```markdown
 This is a file without a heading
 ```
 
-To fix this, add a heading to the top of your file:
+To fix this, add a top level heading to the beginning of the file:
 
 ```markdown
 # File with heading
@@ -1355,10 +1383,10 @@ To fix this, add a heading to the top of your file:
 This is a file with a top level heading
 ```
 
-The `level` parameter can be used to change the top level (ex: to h2) in cases
+Note: The `level` parameter can be used to change the top level (ex: to h2) in cases
 where an h1 is added externally.
 
-If front matter is present and contains a [YAML](https://en.wikipedia.org/wiki/YAML)
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains a
 `title` property (commonly used with blog posts), this rule will not report a
 violation. To use a different property name in front matter, specify the text
 of a regular expression via the `front_matter_title` parameter. To disable the
@@ -1516,3 +1544,62 @@ Or with reference syntax as:
 Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/),
 [Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and
 [other locations](https://www.phase2technology.com/blog/no-more-excuses-definitive-guide-alt-text-field).
+
+<a name="md046"></a>
+
+## MD046 - Code block style
+
+Tags: code
+
+Aliases: code-block-style
+
+Parameters: style ("consistent", "fenced", "indented"; default "consistent")
+
+This rule is triggered when unwanted or different code block styles are used in
+the same document.
+
+In the default configuration this rule reports a violation for the following document:
+
+    Some text.
+
+        # Indented code
+
+    More text.
+
+    ```ruby
+    # Fenced code
+    ```
+
+    More text.
+
+To fix violations of this rule, use a consistent style (either indenting or code fences).
+
+The specified style can be specific (`fenced`, `indented`) or simply require that usage
+be consistent within the document (`consistent`).
+
+<a name="md047"></a>
+
+## MD047 - Files should end with a single newline character
+
+Tags: blank_lines
+
+Aliases: single-trailing-newline
+
+This rule is triggered when there is not a single newline character at the end of a file.
+
+Example that triggers the rule:
+
+```markdown
+# Heading
+
+This file ends without a newline.[EOF]
+```
+
+To fix the violation, add a newline character to the end of the file:
+
+```markdown
+# Heading
+
+This file ends with a newline.
+[EOF]
+```

package/example/standalone.js

@@ -5,8 +5,8 @@ const markdownlint = require("../lib/markdownlint");
 const options = {
   "files": [ "good.md", "bad.md" ],
   "strings": {
-    "good.string": "# good.string\n\nThis string passes all rules.",
-    "bad.string": "#bad.string\n\n#This string fails\tsome rules."
+    "good.string": "# good.string\n\nThis string passes all rules.\n",
+    "bad.string": "#bad.string\n\n#This string fails\tsome rules.\n"
   }
 };
 

package/helpers/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 David Anson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/helpers/README.md

@@ -0,0 +1,50 @@
+# markdownlint-rule-helpers
+
+> A collection of `markdownlint` helper functions for custom rules
+
+## Overview
+
+The [Markdown](https://en.wikipedia.org/wiki/Markdown) linter
+[`markdownlint`](https://github.com/DavidAnson/markdownlint) offers a variety of built-in validation
+[rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md) and supports the
+creation of [custom rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/CustomRules.md).
+The internal rules share various helper functions; this package exposes those for reuse by custom rules.
+
+## API
+
+_Undocumented_ - This package exports the internal functions as-is. The APIs were not originally meant
+to be public, are not officially supported, and may change from release to release. There are brief
+descriptive comments above each function, but no [JSDoc](https://en.m.wikipedia.org/wiki/JSDoc)
+annotations. That said, some of what's here will be useful to custom rule authors and may avoid
+duplicating code.
+
+## Example
+
+```js
+const { forEachLine, getLineMetadata } = require("markdownlint-rule-helpers");
+
+module.exports = {
+  "names": [ "every-n-lines" ],
+  "description": "Rule that reports an error every N lines",
+  "tags": [ "test" ],
+  "function": (params, onError) => {
+    const n = params.config.n || 2;
+    forEachLine(getLineMetadata(params), (line, lineIndex) => {
+      const lineNumber = lineIndex + 1;
+      if ((lineNumber % n) === 0) {
+        onError({
+          "lineNumber": lineNumber,
+          "detail": "Line number " + lineNumber
+        });
+      }
+    });
+  }
+};
+```
+
+See also: [`markdownlint` built-in rule implementations](https://github.com/DavidAnson/markdownlint/tree/master/lib).
+
+## Tests
+
+_None_ - The entire body of code is tested to 100% coverage by the core `markdownlint` project,
+so there are no additional tests here.