davidanson / markdownlint Goto Github PK
View Code? Open in Web Editor NEWA Node.js style checker and lint tool for Markdown/CommonMark files.
License: MIT License
A Node.js style checker and lint tool for Markdown/CommonMark files.
License: MIT License
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.
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?
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.
It would be nice if markdownlint could support shareable configs like eg. ESLint does.
Here's a few checks that I would like to have:
“”
instead of ""
.’
instead of '
.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.
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.
for example
func main() {
r := gin.Default()
r.GET("/", func(c *gin.Context) {
c.String(http.StatusOK, "Hello from %v", "Gin")
})
r.Run(":3000")
}
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 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.
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?
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
A rule to dissallow inline-style links would be a nice enhancements.
Possible configuration parameters:
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?
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 :)
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?
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
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.
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:
{
"MD003": { "style": "setext_with_atx_closed" }
}
Test of VS Code 'markdownlint' Extension
==
Setext Header
--
## ATX Header
### ATX_Closed Header ###
Some text.
setext_with_atx_closed
value for the style
property is unknown to the extension.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.
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).
Writing `
is marked as violating MD038 no-space-in-code
`` ` ``
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.
Why did you choose numbers ? Is there any references somewhere ?
Some others linters are using clear key (eg: eslint, styelint etc)
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?
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.
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…)
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.
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.
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?
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:
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.
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
Example:
- first paragraph of the item
second paragraph of the same item
(note: although this is not visible, line 2 is exactly 4 paragraphs)
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.
It would be nice if I could call markdownlint
from my NPM/build scripts... :)
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.
Such as:
var schema = require('markdownlint/rules-schema');
// use schema
From https://raw.githubusercontent.com/DavidAnson/vscode-markdownlint/master/config-schema.json
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?
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.
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.
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:
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.
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.
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.
Adding a rule to check for file naming would be a nice enhancement.
Guidelines which for example we currently are using:
a-z 0-9 - .
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.
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.
When validating successfully a .md
file, the utility prints an empty new line. This is not needed IMO.
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}`
});
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.
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
#
-
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.