9214242b0c
Closes GH-151. |
||
---|---|---|
doc | ||
packages | ||
script | ||
.editorconfig | ||
.gitignore | ||
.remarkrc.js | ||
.travis.yml | ||
lerna.json | ||
LICENSE | ||
logo.svg | ||
package.json | ||
readme.md | ||
screenshot.png | ||
test.js |
remark-lint is a markdown code style linter. Another linter? Yes. Ensuring the markdown you (and contributors) write is of great quality will provide better rendering in all the different markdown parsers, and makes sure less refactoring is needed afterwards.
What is quality? That’s up to you, but there are sensible presets.
remark-lint is built on remark, a powerful markdown processor powered by plugins (such as this one).
Table of Contents
- Installation
- Command line
- Programmatic
- Rules
- Configuring remark-lint
- Using remark to fix your markdown
- Editor Integrations
- List of Presets
- List of External Rules
- Related
- License
Installation
npm:
npm install remark-lint
Command line
Use remark-lint
with remark-cli
, and a preset.
npm install --save remark-cli remark-preset-lint-recommended
Then, configure remark in your package.json
:
// ...
"scripts": {
"lint-md": "remark ."
},
// ...
"remarkConfig": {
"plugins": ["remark-preset-lint-recommended"]
}
// ...
Let’s say there’s an example.md
, which looks as follows:
* Hello
[World][]
Now, running our lint-md
script with npm, npm run lint-md
, yields:
example.md
1:3 warning Incorrect list-item indent: add 2 spaces list-item-indent
3:1-3:10 warning Found reference to undefined definition no-undefined-references
⚠ 2 warnings
See doc/rules.md
for what those warnings are (and how to
turn them off).
Programmatic
Use remark-lint
together with remark
:
npm install remark remark-lint remark-lint-first-heading-level
Let’s say example.js
looks as follows:
var report = require('vfile-reporter');
var remark = require('remark');
var styleGuide = require('remark-preset-lint-markdown-style-guide');
var file = remark().use(styleGuide).processSync('_Hello world_');
console.log(report(file));
Now, running node example.js
yields:
1:1-1:14 warning Emphasis should use `*` as a marker emphasis-marker remark-lint
⚠ 1 warning
Rules
doc/rules.md
lists all available official rules.
Configuring remark-lint
remark-lint is a remark plug-in and supports configuration through its configuration files.
An example .remarkrc
file could look as follows:
{
"plugins": [
"remark-preset-lint-recommended",
["remark-lint-list-item-indent", false]
]
}
Where the object at plugins.lint
is a map of ruleId
s and
their values, which precede over presets.
Using our example.md
from before:
* Hello
[World][]
Now, running npm run lint-md
yields:
example.md
3:1-3:10 warning Found reference to undefined definition no-undefined-references
⚠ 2 warnings
In addition, you can also provide configuration comments to turn a rule
on or off inside a file. Note that you cannot change what a setting,
such as maximum-line-length
, just whether they are shown or not.
Read more about configuration comments in
remark-message-controls documentation.
The following file will warn twice for the duplicate headings:
# Hello
## Hello
### Hello
The following file will warn once (the second heading is ignored, but the third is re-enabled):
# Hello
<!--lint disable no-duplicate-headings-->
## Hello
<!--lint enable no-duplicate-headings-->
### Hello
Note
: You’ll need the blank lines between comments and other nodes!
Using remark to fix your markdown
One of remark’s cool parts is that it compiles to very clean, and highly cross-vendor supported markdown. It’ll ensure list items use a single bullet, emphasis and strong use a standard marker, and that your table fences are aligned.
remark should be able to fix most of your styling issues automatically, and I strongly suggest checking out how it can make your life easier 👍
Editor Integrations
Currently, remark-lint is integrated with Atom through linter-markdown.
If you want to run all of remark from Atom, use linter-remark.
To run remark, optionally with remark-lint from Gulp, use gulp-remark.
I’m very interested in more integrations. Let me know if I can help.
List of Presets
Presets can be loaded through the preset
setting.
remark-preset-lint-consistent
— rules that enforce consistencyremark-preset-lint-markdown-style-guide
— rules that enforce the markdown style guideremark-preset-lint-recommended
— rules that prevent mistakes or syntaxes that do not work correctly across vendors
List of External Rules
External rules can be loaded just like normal rules.
⚠️ means the rule has not been updates for remark-lint 6.0.0.
vhf/remark-lint-alphabetize-lists
— Ensure list items are in alphabetical order;RichardLitt/remark-lint-appropriate-heading
— Check that the top-level heading matches the directory name;vhf/remark-lint-blank-lines-1-0-2
— Ensure a specific number of lines between blocks;vhf/remark-lint-books-links
— Ensure links in lists of books follow a standard format;Qard/remark-lint-code
— Lint fenced code blocks by corresponding language tags, currently supporting ESLint.vhf/remark-lint-no-empty-sections
— Ensure every heading is followed by content (forming a section);verekia/remark-lint-no-leading-spaces
— ⚠️ Warn about leading white-space;wemake-services/remark-lint-list-item-punctuation
— ⚠️ check if list items end in periods;chcokr/remark-lint-sentence-newline
— ⚠️ Ensure sentences are followed by a newline;verekia/remark-lint-no-trailing-spaces
— ⚠️ Warn about trailing white-space;vhf/remark-lint-no-url-trailing-slash
— Ensure that thehref
of links has no trailing slash.
Related
wooorm/remark-validate-links
— Validate if links point to existing headings and files in markdown.