davidanson/markdownlint

A Node.js style checker and lint tool for Markdown/CommonMark files.

markdownlint's Issues

Unordered sublist in ordered list

I'm having trouble getting an unordered sublist in an ordered list to pass linting with the default config. I've tested in playground and with markdownlint-cli.

With 2 space indent I get MD006 and also see 3 distinct lists - ordered, unordered, ordered - in the playground preview:

# sublist test

1. foo
  - bar
  - baz
1. foo

With 4 (or 3, or 5 just for kicks) space indent I get MD007:

# sublist test

1. foo
    - bar
    - baz
1. foo

An unordered sublist with 2 space indent in an unordered parent works fine:

# sublist test

- foo
  - bar
  - baz
- foo

As does inverting the structure of what I'm trying to achieve: an ordered sublist with 2 space indent in an unordered parent:

# sublist test

- foo
  1. bar
  1. baz
- foo

I may be missing a spacing requirement in the CommonMark spec, but feels like either one of the first two examples should pass if the fourth does?

Make `no-multiple-blanks` configurable

Since this is mostly aesthetic, making the option configurable will offer more flexibility.

Say, allow max: 3 blank lines would allow for 1 up to 3 blank lines.

Add rule for checking proper formating of fenced code block inside lists

Writing fenced code blocks inside of ordered and unordered lists might not be the most obvious thing. A rule indicating mistakes might be really helpful in this case.

Stuff to check:

• There needs to be a new line before and following any fenced code block inside of a ordered or unordered list

Suggestion: Add rules json schema

Such as:

var schema = require('markdownlint/rules-schema');

// use schema

From https://raw.githubusercontent.com/DavidAnson/vscode-markdownlint/master/config-schema.json

Consider using key for rules instead of number

Why did you choose numbers ? Is there any references somewhere ?

Some others linters are using clear key (eg: eslint, styelint etc)

MD041 (first-line-h1) and HTML comments

I find it convenient to disable some rules for the whole file by adding a markdownlint marker to the top of the file (as I would do with JSLint directives, for example):

<!-- markdownlint-disable line-length -->
# Header

...

But this violates MD041 (first-line-h1) rule.
I think MD041 (first-line-h1) should ignore HTML comments.

MD029 - Ordered list item prefix

I have a document where I have an ordered list and I get the warning above on every item after 1.
So if I have the following code I get the MD029 error on #'s 2, 3 and 4.

1. A computer or access to a computer that we can install software on. Preferably under our own user account. 2. Access to the internet. 3. A place where you can take and save notes. 4. Personal Grit

Is this normal behavior, or is the linter not recognizing the OL properly?

Bogus MD0036 error

Take this snippet for instance:

* `io.js 1.6.2`, `io.js 1.6.3` x86 and x64 added. Use `Install-Product node 1` cmdlet to switch runtime to the latest io.js version.
* `Node.js 0.10.38`, `Node.js 0.12.2` x86 and x64 added. Use `Install-Product node 0` cmdlet to switch runtime to the latest Node.js version or `Install-Product node 0.10` to the latest 0.10.x build.
    * Node.js 0.10.38 x86 is default Node.js in `PATH`
* **Azure SDK 2.5.1**
* [Microsoft Visual Studio Installer Projects](https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-0fbf6151054d) extension installed (`.vdproj` support).
* [Bundler 1.9.2](https://rubygems.org/gems/bundler/versions/1.9.2) is pre-installed to all Rubies.
* **Python 2.7.9** replaces Python 2.7.8 in `C:\Python27` and `C:\Python27-x64`.
* **Python 3.4.3** replaces Python 3.4.1 in `C:\Python34` and `C:\Python34-x64`.

Another example:

3. Run `install` scripts
4. Patch `AssemblyInfo` files
5. Modify `hosts` files
6. Start services
7. **Build**
    * Run `before_build` scripts
    * Run msbuild
    * Run `after_build` scripts
8. **Test**

That is an emphasis and not a header.

proper-names should allow different formatting when a URL is used as link text

Given the following configuration:

{
  "proper-names": {
    "names": [
      "GitHub"
    ]
  }
}

I can write this:

Awesome things related to Vue available at GitHub

Awesome things related to Vue available at [GitHub](https://github.com/vuejs/awesome-vue)

But not any of this:

Awesome things related to Vue available at github.com

Awesome things related to Vue available at [github.com](https://github.com/vuejs/awesome-vue)
Awesome things related to Vue available at [github.com/vuejs](https://github.com/vuejs/awesome-vue)
Awesome things related to Vue available at [github.com/vuejs/awesome-vue](https://github.com/vuejs/awesome-vue/)

I also tried adding "github.com" to the configuration both before and after "GitHub" but it didn't help, I still got the error.

---

I believe it's obvious that the latter should also be allowed here. When linking between domains, I quite frequently prefer writing the URL for the user, but will use the link formatting to only write the relevant part and make the link more readable. I might drop the protocol, parameters, trailing slashes and such.

I think proper-names should exempt all URLs and emails. This seems to be the intention as well as the code does not trigger errors from bare URLs, but it still disallows using the URL pattern as a user-facing link text, which probably isn't what we want.

MD033 "Inline HTML" should allow exceptions

My markdown files contain certain html tags (like <kbd>) that just can't be expressed in markdown. I'd suggest to extend the configuration option to accept an array of tags that are considered safe for use in a document.

I generally want to be warned about html in my markdown, but there are situations where I actually need to use the html. I was wondering if there is any way to mark those situations inline, like you would with eslint's /*eslint-disable foobar */. (long shot, I don't see any obvious notation for this…)

Request: No empty link rule

When working on large documents, sometimes placeholder links are added with the expectation they will be defined later. For example:

[foo]()

[bar](#)

Such links are somewhat difficult to spot in big documents. The rule would warn against those patterns.

Note: A # link is sometimes used to jump to top of document, however similar effect can be achieved by linking to main heading or a html anchor tag.

MD030, Spaces after list markers isn’t enforced if 0 spaces

Here’s an example of incorrect Markdown:

-Some stuff
-More stuff
- Things

I would like to enforce a single space after those dashes in the list. Without the space Markdown interprets it as a paragraph.

Important configuration I have turned on:

{
  "ul-style": {
    "style": "dash"
  },
  "list-indent": true,
  "ul-start-left": true,
  "ul-indent": {
    "indent": 2
  },
  "list-marker-space": {
    "ul_single": 1,
    "ol_single": 1,
    "ul_multi": 1,
    "ol_multi": 1
  },
}

What error message I do see:

MD032 — Lists should be surrounded by blank lines.

Which doesn’t make sense to me because those aren’t separate lists. It’s interpreting the last, correct dash, as a list and the other two as paragraphs.

Use case:

I teach beginners, people who have never written a line of Markdown before. The idea that a missing space can have such an impact is foreign. I’d like to use the linter to find these simple mistakes beforehand.

Any thoughts would be appreciated. Thanks.

MD009 for list continuation

when you make a multi paragraphs list, you have to continue indentation on empty lines. In this case, rule MD009 report an error.
To solve this issue, MD009 should not trigger errors for a line with only spaces if

• previous lines starts by at least the same amount of lines and following line starts by exactly the same amount of spaces
• or previous lines starts by exactly the same amount of lines and following line starts by at least the same amount of spaces

Example:

-   first paragraph of the item
    
    second paragraph of the same item

(note: although this is not visible, line 2 is exactly 4 paragraphs)

MD044 - Links and code should be excluded from checks

First of all, thanks for this great tool. I've been experimenting with it for the last couple of days and it works great.

I'm really interested in this rule, but it fails short with its current implementation. Example:

  "proper-names": {
      "names": [
          "GitHub"
      ]
  }

All docs fail where there's a link to GitHub. I think there should be an option to exclude links, URLs, and code from this check, and it should probably be true by default.

ordered and unordered lists recognized where there are none

The following text triggers linting rules MD 29 and 30/32.

This example text triggers linting rules number 29 and
32. If no sentence follows the previous one, linting rules 29 and 30 are triggered.

A possible solution would be to search first for dot (.) in the line preceding the supposed ordered list. Only when . is found should rules 29, 30/32 be triggered.

Case of falsely recognised unordered list:

This example text triggers linting rule number 32
- and sometimes rule number 4.

Rule MD004 incorrectly flagging on an Ordered List

I'm getting flagged on the following. Am I missing something obvious?

1. Fork the repository on Github
+ Create a named feature branch (like `add_component_x`)
+ Write your change
+ Write tests for your change (if applicable)
+ Run the tests, ensuring they all pass
+ Submit a Pull Request using Github

ignore hard-tabs in code block

for example

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.String(http.StatusOK, "Hello from %v", "Gin")
    })

    r.Run(":3000")
}

Ignore indenting within code blocks

I write code with tabs and when I copy paste the code inside my markdown files, markdownlint complains about hard tabs. Wouldn't be a good idea to not enforce the indenting rule within code block s to allow any kind of indent?

A command line interface

It would be nice if I could call markdownlint from my NPM/build scripts... :)

MD013 (line-length) and link tooltips

A link can have a tooltip with whitespace, e. g.

[Open a pull request](https://help.github.com/articles/using-pull-requests/ "Using pull requests · GitHub Help")

It is impossible to break it into multiple lines.
I think MD013 (line-length) should ignore lines with links that have tooltips.

Long headers cannot be multi-line (MD022) or longer than line length (MD013)

Either rule should be deactivated in case of headers, most probably rule MD013.

Alternatively, add another linting rule which allows to influence this behaviour in a way which would ensure compatibility with Markdown.

Consider highlighting trailing space when encountering MD009

Currently when MD009 is encountered, the entire line is highlighted to indicate that there is a trailing space. This is distracting when you're constantly typing. Highlighting just the last space, or perhaps not showing the error indication if the cursor is currently active on the line would make it less obtrusive.

Enhancement: Custom error messages

Rules

Currently rules have a static error message, it would be useful if they could generate context-sensitive errors, for example:

errors.push({
  lineNumber: whatever,
  error: `The '${headingText}' heading should be at level ${expectedLevel}`
});

Styles

An optional top-level error message that gets output upon the first error for a given batch of documents.

options.config._guidance = 'Please refer to the style guide for more information on the errors below: http://whatever.com/styleguide'

This would be particularly useful in CI builds of open source projects to help guide contributors to the style guide or templates, etc.

Add rule to check for file naming

Adding a rule to check for file naming would be a nice enhancement.

Guidelines which for example we currently are using:

• Filename needs to be lowercase
• Allowed characters: a-z 0-9 - .

Erroneous MD003 warning

MD003/header-style: Header style [Expected: setext; Actual: atx]

I get this warning for ### Header Level 3, even though your documentation says it is valid...

The setext_with_atx and settext_with_atx_closed doc styles allow atx-style headers of level 3 or more in documents with setext style headers:

Shareable configs

It would be nice if markdownlint could support shareable configs like eg. ESLint does.

Maximum line width

First off: Its really great that you work on this 👍 markdown files make out a lot of our work and linting it can really help. That being said,...

One important issue that I have with markdown is if the paragraphs should be multiline or not. I am of the opinion that paragraphs should be broken after 80 characters to make sure that pull requests go through smoother (and see changes easier). Do you think it would be possible to add an optional check for the maximum line size?

Require structure only for certain files / paths

Is there a way to have MD043 only required for certain files or paths, but not for others?

Or is there a way to exclude this rule for certain files?

I tried with <!-- markdownlint-disable MD043 --> but couldn't get it working.

Proposed rule: enforce typography

Here's a few checks that I would like to have:

• quotes: use proper “” instead of "".
• apostrophes: use proper apostrophes ’ instead of '.
• punctuation_space: enforce one space after a punctuation symbol, unless it's followed by a new line.
• double_spaces: no double spaces.

I think code should be excluded by default for all these checks.

For the first two, Atom has a really nice package that might be used as inspiration.

Trailing space in paragraph bug

There seems to be a bug in the trailing space matching of some kind, but only errors when there’s front matter. I cannot recreate the error in the demo so it could also be related to resultVersion: 1.

This is the code that throws the error:

---
basic-card: |
  The basic card is used to showcase the dogs that are available for adoption. It includes a button but never links itself.
---

The cards provide a way to highlight and group important information. 

There’s a trailing space right at the end of “information. ” and this is the error I get:

TypeError: Cannot read property 'match' of undefined on line 258

If I strip the front matter it seems to work okay.

---

Version: 0.4.0

MD029 is triggered on any multiline ordered list items.

I am using the markdownlint v0.6.2 and I am seeing that the MD029 rule is always triggered even when using the sample provided inside the rule.
i.e.

1. Do this.
2. Do that.
3. Done.

should pass the issue but it is generating green swiggle with MD029 tooltip.

Request: Mandatory headings

Would it be possible to get a rule which enforces mandatory headings in a file?

For example, in documentation, there may be a style guide that requires the docs to have a specific set of headers.

The rule would take an array of strings, each string being a header that must exist in the file. The rule is violated if any of the headers in the array are not found in the file.

If possible, an optional boolean flag (false by default) would make the rule ensure that the headers are in the same order as those specified in the array.

Unordered sublist with different symbol

When writing an unordered sublist I like to use a different list symbol rather than the same used for the main list:

- item 1
- item 2
  + subitem 1
  + subitem 2

In my opinion this should be fine, but I get a MD004 warning instead. I suggest to modify the linter not to raise a warning in this case.

It would be nice if MD002 could be configured

When I use markdown files in a static site generator I usually have a template use the title as an h1; I'd like to configure MD002 to check if an h2 is used first.

Support for presets?

With the latest changes in 0.5.0 that introduce extends, I'm wondering what your thoughts are about supporting a concept of presets? This is similar to what ESLint offers and I think it'd be a useful addition this tool.

For some background, we currently maintain several projects that have .markdownlint.json files. For us, it'd be great to centrally define these rules, and then just pull that dependency into each project. We could then better communicate to our team what has changed and why :)

Add support for custom rules

Hi, nice tool! Thanks.

I would like to add my own custom rules, similar to rules param object, declare custom rules in the config. Would you consider?

MD030 (list-marker-space) produces buggy warning message

#

-

1.

The above code produces the following warnings:

3 - MD030 Spaces after list markers [Expected: 1; Actual: true]
5 - MD030 Spaces after list markers [Expected: 1; Actual: true]

Something is not right here.

The bug is reproducible on the markdownlint demo page.

Automatically disable MD041 for documents with Front Matter

Documents that use front matter, such as jekyll's markdown format, typically contain a title property that becomes the title of the document. When this is present, it would be nice to automatically disable MD041 since the title is already present in the front matter.

rule MD034 flags URL in fenced block as "bare url", unlike mdl

A URL inside of a fenced code block is marked as a "bare url" by markdownlint.

However, the ruby-based mdl doesn't mark the same line as a bare url.

Please resolve this difference. Thanks.

Example:
$ cat test-fenced-url.md

# Error with URL in Fenced Code Block

    ````text
http://lms.com/pens.cgi?command=collect&pens-version=1.0.0
&package-type=scorm-pif&package-type-version=1.2&package-format=zip
&package-id=http%3A%2F%2Fwww.author.com%3A994646572378864600-1085069139609
&package-url=http%3A%2F%2Fauthor.com%2Fpackages%2F1085069139609.zip
&package-url-expiry=2005-05-20T16%3A05%3A39Z&client=Author
&receipt=http%3A%2F%2Fauthor.com%2Fpens.cgi
&alerts=http%3A%2Fauthor.com%2Fpens.cgi
    ````

The above example will "pass" review by mdl, but markdownlint will trigger a warning:

$ mdl test-fenced-url.md
$ markdownlint test-fenced-url.md
test-fenced-url.md: 3: MD034 Bare URL used

escape backtick violates MD038

Writing ` is marked as violating MD038 no-space-in-code

`` ` ``

MD011: false positive for parenthesis plus footnote

I first posted this to the Ruby project by mistake, but at least means that both Ruby and Node users will benefit from it.

Here is what it originally read:

---

(...)[^footnote]

Is regarded as a reverse link, because markdownlint considers footnote syntax (part Markdown Extra) a link.

---

markdownlint/markdownlint#132

Add rule to enforce letter case of project names [WAS: How to add custom rules?]

Hi,

I checked the docs/source but I didn't see any obvious extension mechanism (apart from forking). Do you have some preferred way on how to handle custom rules? I can see the rule mechanism itself is quite simple. If it was possible to inject new ones through the API somehow (match through npm/Node), I could likely do what I want (I need to verify certain word is lowercase always).

spurious warnings about question or exclamation marks in a header

a header like this one:

# Why?

produces a MD026 warning about trailing punctutation in the header. the same happens when an exclamation mark is used.

this should not happen.

Don't print empty lines on valid Markdown

When validating successfully a .md file, the utility prints an empty new line. This is not needed IMO.

setext_with_atx_closed not available in Virtual Studio Code extension

I just installed the markdownlint extension in VS Code. I was going nuts trying to figure out why I couldn't get the .json config to take setext_with_atx_closed, when all the other options (including setext_with_atx) worked fine. So I stumbled on your commit history and see you've only just implemented it. I assume, then, that this change has not been migrated into the VS Code extension. Will you be updating the extension soon, or should it be already working?

To reproduce the symptom:

• Create file .markdownlint.json in project folder with the following content:

{
    "MD003": { "style": "setext_with_atx_closed" }
}

• In VS Code with markdownlint extension installed, open the project folder.
• Create a new file, set its language to Markdown, and enter the following lines:

Test of VS Code 'markdownlint' Extension
==

Setext Header
--

## ATX Header

### ATX_Closed Header ###

Some text.

• Observe that all headers are flagged with warnings for rule MD003. Presumably, the setext_with_atx_closed value for the style property is unknown to the extension.

CommonMark mention

Currently README.md call markdownlint A Node.js style checker and lint tool for Markdown files.

Should CommonMark be mentioned too?

As far as I understood it covers CommonMark pretty good. CommonMark nowadays is becoming a de-facto standard, because it has spec unlike Markdown. I see that you included link to this spec in README.md.

MD029 (ol-prefix) and nested unordered lists in ordered lists

If I use the following rule:

{
    "ol-prefix": {
        "style": "ordered"
    }
}

then markdownlint says "Ordered list item prefix (Expected: 1; Actual: 2)" to the following code:

1. a
- b
2. c
- d

It looks like markdownlint thinks that 2. c is the beginning of a new list, but it's the second item of the single ordered list.

If I indent the unordered lists, markdownlint says "Consider starting bulleted lists at the beginning of the line".

What is the correct way of using nested unordered lists in ordered lists?

Add ability to disable specific rule(s) for specific file(s)

Hello, I'm working on the ESLint project, which uses this module. In general, we want to prohibit tabs in our markdown (using rule MD010), but there is one file where I need to use tabs in an example of the indent rule. Is there a way to turn off just that rule, for just that file? If not, is that a feature you would consider adding?

Allow atx_closed with setext in rule MD003

Currently rule MD003 has the style option of setext_with_atx, but this does not allow atx_closed to be used with setext. Either adding a new style of setext_with_atx_closed to the rule or allowing atx_closed be acceptable when using the style setext_with_atx would be nice. Thoughts? Is there a preference one way or the other?

Add rule to check for inline-style links

A rule to dissallow inline-style links would be a nice enhancements.

Possible configuration parameters:

• Disallow all inline-style links
• Allow inline-style links in lists only
• Allow all inline-style links