Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-09-21 21:30:47 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Add README.md, Rules.md, test for project files.

Browse source
This commit is contained in:
David Anson 2015-03-12 23:42:06 -07:00
parent 77da8da9cf
commit f6d0986cc5
3 changed files with 742 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

44
README.md Normal file
View file

@ -0,0 +1,44 @@
# markdownlint
> A Node.js style checker/lint tool for Markdown files.
## Install
```shell
npm install markdownlint --save-dev
```
## Overview
The [Markdown](http://en.wikipedia.org/wiki/Markdown) markup language is
designed to be easy to read, write, and work with. The language has succeeded,
but its flexibility is both a benefit and a drawback. Many stylistic decisions
are left to the author, so formatting can be inconsistent. Some constructs
don't work well in all parsers and should be avoided.
`markdownlint` is a [static analysis](http://en.wikipedia.org/wiki/Static_program_analysis)
tool for [Node.js](https://nodejs.org/) and [io.js](https://iojs.org/) with a
library of rules to enforce standards and correctness for Markdown files. It
was inspired by - and heavily influenced by - Mark Harrison's [markdownlint
for Ruby](https://github.com/mivok/markdownlint): the rules, rule
documentation, and tests for `markdownlint` come directly from that project.
> Aside: If you need a Ruby implementation or CLI, please consider
> [mdl](https://rubygems.org/gems/mdl). If you work with both platforms, most
> of what you know can be applied directly.
## Rules
See [Rules.md](doc/Rules.md)
## Usage
...
```js
...
```
## Release History
* 0.0.1 - Initial release.

684
doc/Rules.md Normal file
View file

@ -0,0 +1,684 @@
# Rules
This document contains a description of all rules, what they are checking for,
as well as an examples of documents that break the rule and corrected
versions of the examples.
## MD001 - Header levels should only increment by one level at a time
Tags: headers
This rule is triggered when you skip header levels in a markdown document, for
example:
# Header 1
### Header 3
We skipped out a 2nd level header in this document
When using multiple header levels, nested headers should increase by only one
level at a time:
# Header 1
## Header 2
### Header 3
#### Header 4
## Another Header 2
### Another Header 3
## MD002 - First header should be a h1 header
Tags: headers
This rule is triggered when the first header in the document isn't a h1 header:
## This isn't a H1 header
### Another header
The first header in the document should be a h1 header:
# Start with a H1 header
## Then use a H2 for subsections
## MD003 - Header style
Tags: headers
Parameters: style
This rule is triggered when different header styles (atx, setext, and 'closed'
atx) are used in the same document:
# ATX style H1
## Closed ATX style H2 ##
Setext style H1
===============
Be consistent with the style of header used in a document:
# ATX style H1
## ATX style H2
Note: the configured header style can be a specific style to use (atx,
atx_closed, setext), or simply require that the usage be consistent within the
document.
## MD004 - Unordered list style
Tags: bullet, ul
Parameters: style
This rule is triggered when the symbols used in the document for unordered
list items do not match the configured unordered list style:
* Item 1
+ Item 2
- Item 3
To fix this issue, use the configured style for list items throughout the
document:
* Item 1
* Item 2
* Item 3
Note: the configured list style can be a specific symbol to use (asterisk,
plus, dash), or simply require that the usage be consistent within the
document.
## MD005 - Inconsistent indentation for list items at the same level
Tags: bullet, ul, indentation
This rule is triggered when list items are parsed as being at the same level,
but don't have the same indentation:
* Item 1
* Nested Item 1
* Nested Item 2
* A misaligned item
Usually this rule will be triggered because of a typo. Correct the indentation
for the list to fix it:
* Item 1
* Nested Item 1
* Nested Item 2
* Nested Item 3
## MD006 - Consider starting bulleted lists at the beginning of the line
Tags: bullet, ul, indentation
This rule is triggered when top level lists don't start at the beginning of a
line:
Some text
* List item
* List item
To fix, ensure that top level list items are not indented:
Some test
* List item
* List item
Rationale: Starting lists at the beginning of the line means that nested list
items can all be indented by the same amount when an editor's indent function
or the tab key is used to indent. Starting a list 1 space in means that the
indent of the first nested list is less than the indent of the second level (3
characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
## MD007 - Unordered list indentation
Tags: bullet, ul, indentation
Parameters: indent
This rule is triggered when list items are not indented by the configured
number of spaces (default: 2).
Example:
* List item
* Nested list item indented by 3 spaces
Corrected Example:
* List item
* Nested list item indented by 2 spaces
Rationale (2 space indent): 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.
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
information.
In addition, this is a compatibility issue with multi-markdown parsers, which
require a 4 space indents. See
<http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>
for a description of the problem.
## MD009 - Trailing spaces
Tags: whitespace
This rule is triggered on any lines that end with whitespace. To fix this,
find the line that is triggered and remove any trailing spaces from the end.
## MD010 - Hard tabs
Tags: whitespace, hard_tab
This rule is triggered by any lines that contain hard tab characters instead
of using spaces for indentation. To fix this, replace any hard tab characters
with spaces instead.
Example:
Some text
* hard tab character used to indent the list item
Corrected example:
Some text
* Spaces used to indent the list item instead
## MD011 - Reversed link syntax
Tags: links
This rule is triggered when text that appears to be a link is encountered, but
where the syntax appears to have been reversed (the `[]` and `()` are
reversed):
(Incorrect link syntax)[http://www.example.com/]
To fix this, swap the `[]` and `()` around:
[Correct link syntax](http://www.example.com/)
## MD012 - Multiple consecutive blank lines
Tags: whitespace, blank_lines
This rule is triggered when there are multiple consecutive blank lines in the
document:
Some text here
Some more text here
To fix this, delete the offending lines:
Some text here
Some more text here
Note: this rule will not be triggered if there are multiple consecutive blank
lines inside code blocks.
## MD013 - Line length
Tags: line_length
Parameters: line_length
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.
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
being forced to break them in the middle.
## MD014 - Dollar signs used before commands without showing output
Tags: code
This rule is triggered when there are code blocks showing shell commands to be
typed, and the shell commands are preceded by dollar signs ($):
$ ls
$ cat foo
$ less bar
The dollar signs are unnecessary in the above situation, and should not be
included:
ls
cat foo
less bar
However, an exception is made when there is a need to distinguish between
typed commands and command output, as in the following example:
$ ls
foo bar
$ cat foo
Hello world
$ cat bar
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>
for more information.
## MD018 - No space after hash on atx style header
Tags: headers, atx, spaces
This rule is triggered when spaces are missing after the hash characters
in an atx style header:
#Header 1
##Header 2
To fix this, separate the header text from the hash character by a single
space:
# Header 1
## Header 2
## MD019 - Multiple spaces after hash on atx style header
Tags: headers, atx, spaces
This rule is triggered when more than one space is used to separate the
header text from the hash characters in an atx style header:
# Header 1
## Header 2
To fix this, separate the header text from the hash character by a single
space:
# Header 1
## Header 2
## MD020 - No space inside hashes on closed atx style header
Tags: headers, atx_closed, spaces
This rule is triggered when spaces are missing inside the hash characters
in a closed atx style header:
#Header 1#
##Header 2##
To fix this, separate the header text from the hash character by a single
space:
# Header 1 #
## Header 2 ##
Note: this rule will fire if either side of the header is missing spaces.
## MD021 - Multiple spaces inside hashes on closed atx style header
Tags: headers, atx_closed, spaces
This rule is triggered when more than one space is used to separate the
header text from the hash characters in a closed atx style header:
# Header 1 #
## Header 2 ##
To fix this, separate the header text from the hash character by a single
space:
# Header 1 #
## Header 2 ##
Note: this rule will fire if either side of the header contains multiple
spaces.
## MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
This rule is triggered when headers (any style) are either not preceded or not
followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after
(except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
not parse headers that don't have a blank line before, and will parse them as
regular text.
## MD023 - Headers must start at the beginning of the line
Tags: headers, spaces
This rule is triggered when a header is indented by one or more spaces:
Some text
# Indented header
To fix this, ensure that all headers start at the beginning of the line:
Some text
# Header
Rationale: Headers that don't start at the beginning of the line will not be
parsed as headers, and will instead appear as regular text.
## MD024 - Multiple headers with the same content
Tags: headers
This rule is triggered if there are multiple headers in the document that have
the same text:
# Some text
## Some text
To fix this, ensure that the content of each header is different:
# Some text
## Some more text
Rationale: Some markdown parses generate anchors for headers based on the
header name, and having headers with the same content can cause problems with
this.
## MD025 - Multiple top level headers in the same document
Tags: headers
This rule is triggered when a top level header is in use (the first line of
the file is a h1 header), and more than one h1 header is in use in the
document:
# Top level header
# Another top level header
To fix, structure your document so that there is a single h1 header that is
the title for the document, and all later headers are h2 or lower level
headers:
# Title
## Header
## Another header
Rationale: A top level header is a 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 header.
## MD026 - Trailing punctuation in header
Tags: headers
Parameters: punctuation
This rule is triggered on any header that has a punctuation character as the
last character in the line:
# This is a header.
To fix this, remove any trailing punctuation:
# This is a header
Note: The punctuation parameter can be used to specify what characters class
as punctuation at the end of the header. For example, you can set it to
`'.,;:!'` to allow headers with question marks in them, such as might be used
in an FAQ.
## MD027 - Multiple spaces after blockquote symbol
Tags: blockquote, whitespace, indentation
This rule is triggered when blockquotes have more than one space after the
blockquote (`>`) symbol:
> This is a block quote with bad indentation
> there should only be one.
To fix, remove any extraneous space:
> This is a blockquote with correct
> indentation.
## MD028 - Blank line inside blockquote
Tags: blockquote, whitespace
This rule is triggered when two blockquote blocks are separated by nothing
except for a blank line:
> This is a blockquote
> which is immediately followed by
> this blockquote. Unfortunately
> In some parsers, these are treated as the same blockquote.
To fix this, ensure that any blockquotes that are right next to each other
have some text in between:
> This is a blockquote.
And Jimmy also said:
> This too is a blockquote.
Alternatively, if they are supposed to be the same quote, then add the
blockquote symbol at the beginning of the blank line:
> This is a blockquote.
>
> This is the same blockquote.
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.
## MD029 - Ordered list item prefix
Tags: ol
Parameters: style
This rule is triggered on 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, which defaults to 'one').
Example valid list if the style is configured as 'one':
1. Do this.
1. Do that.
1. Done.
Example valid list if the style is configured as 'ordered':
1. Do this.
2. Do that.
3. Done.
## MD030 - Spaces after list markers
Tags: ol, ul, whitespace
Parameters: ul_single, ol_single, ul_multi, ol_multi
This rule checks for the number of spaces between a list marker (e.g. '`-`',
'`*`', '`+`' or '`1.`') and the text of the list item.
The number of spaces checked for depends on the document style in use, but the
default is 1 space after any list marker:
* Foo
* Bar
* Baz
1. Foo
1. Bar
1. Baz
1. Foo
* Bar
1. Baz
A document style may change the number of spaces after unordered list items
and ordered list items independently, as well as based on whether the content
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>
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
inside the list:
* Foo
* Bar
* Baz
vs.
* Foo
Second paragraph
* Bar
or
1. Foo
Second paragraph
1. Bar
To fix this, ensure the correct number of spaces are used after list marker
for your selected document style.
## MD031 - Fenced code blocks should be surrounded by blank lines
Tags: code, blank_lines
This rule is triggered when fenced code blocks are either not preceded or not
followed by a blank line:
Some text
```
Code block
```
```
Another code block
```
Some more text
To fix this, ensure that all fenced code blocks have a blank line both before
and after (except where the block is at the beginning or end of the document):
Some text
```
Code block
```
```
Another code block
```
Some more text
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
not parse fenced code blocks that don't have blank lines before and after them.
## MD032 - Lists should be surrounded by blank lines
Tags: bullet, ul, ol, blank_lines
This rule is triggered when lists (of any kind) are either not preceded or not
followed by a blank line:
Some text
* Some
* List
1. Some
2. List
Some text
To fix this, ensure that all lists have a blank line both before and after
(except where the block is at the beginning or end of the document):
Some text
* Some
* List
1. Some
2. List
Some text
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
not parse lists that don't have blank lines before and after them.
Note: List items without hanging indents are a violation of this rule; list
items with hanging indents are okay:
* This is
not okay
* This is
okay

15
test/markdownlint-test.js
View file

@ -2,9 +2,9 @@
var fs = require("fs");
var path = require("path");
var Q = require("q");
var markdownlint = require("../lib/markdownlint");
var shared = require("../lib/shared");
var Q = require("q");
function createTestForFile(file) {
return function testForFile(test) {
@ -67,6 +67,19 @@ fs.readdirSync(__dirname).forEach(function forFile(file) {
}
});
module.exports.projectFiles = function projectFiles(test) {
test.expect(2);
var options = {
"files": [ "README.md" ]
};
markdownlint(options, function callback(err, actual) {
test.ifError(err);
var expected = { "README.md": {} };
test.deepEqual(actual, expected, "Issue(s) with project files.");
test.done();
});
};
module.exports.missingOptions = function missingOptions(test) {
test.expect(2);
markdownlint(null, function callback(err, result) {