markdown-lint
Markdown code style linter that makes your documentation looks nicer.
It’s based on Prettier, Remark & Typograf.
Rationale
Some projects have a lot of documentation inside the repos. Once we decided to start linting their grammar and check for spelling errors. For that purpose we built languagetool-node.
But at the same time we decided to lint the Markdown syntax of those files, as we do with our JS, CSS, etc files. And we’ve created this linter.
Getting Started
To install the tool and use it globally run:
npm install -g @funboxteam/markdown-lint
To install the tool into the project and setup pre-commit hook run:
npm install --dev husky lint-staged @funboxteam/markdown-lint
Project Setup
To automatically lint Markdown files on precommit you should setup husky
and
lint-staged
to work with markdown-lint
in your project’s package.json.
Example:
{
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
},
"lint-staged": {
"*.md": [
"markdown-lint --fix --typograph"
]
}
}
CLI Usage
To check files and directories manually you should run markdown-lint
:
# check the passed file
markdown-lint README.md
# check all the files inside the passed directory (w/o recursive search)
markdown-lint ./docs
# check all the files inside the passed directory (recursively)
markdown-lint -r ./docs
# check the passed file and automatically fix errors
markdown-lint --fix README.md
Options
--fix
— automatically fix errors.--ext <value>
— specify file extensions (default:md
). It’s possible to set several extensions like this:--ext apib --ext txt
.-t, --typograph
— run typograph over the text inside the files.-r, --recursive
— search for files in the subdirectories of the passed directory.-c, --config <file>
— use external config file to extend the default one.-v, --version
— show current tool version.-h, --help
— show help.
Configuration
The linter works upon the Markdown processor called remark.
The linting itself works is done by remark-lint and the set of rules defined in remark-preset-lint-markdown-style-guide.
You may use your own configuration file by passing the path to that file using
--config
option:
markdown-lint --fix --config ~/.markdownlintrc.js README.md
Example of configuration file:
module.exports = {
// prettier is used when `--fix` is passed
prettier: {
// hard wrap lines to 120 characters
printWidth: '120'
},
remark: {
// plugins for remark-lint
plugins: [
// print errors when there're lines longer that 120 characters
[require('remark-lint-maximum-line-length'), 120],
// disable rule `no-inline-padding`
[require('remark-lint-no-inline-padding'), false],
// set `*` as the only allowed marker for unordered list
[require('remark-lint-unordered-list-marker-style'), '*']
],
// settings for remark-stringify which is used when `--fix` is passed
stringifySettings: {
// automatically replace list markers to `*`
bullet: '*'
}
},
typograf: {
// rules API — https://github.com/typograf/typograf/blob/dev/docs/api_rules.md
// list of ruls — https://github.com/typograf/typograf/blob/dev/docs/RULES.en-US.md
locale: ['ru', 'en-US'],
enableRules: [],
disableRules: [
// these rules have to be turned off to make it possible to use typograph
'common/space/delTrailingBlanks',
'common/space/trimLeft',
'common/space/trimRight'
],
rulesSettings: []
}
};
Example
Original text
Linux kernel
============
There are several guides for kernel developers and users. These guides can be rendered in a number of formats, like HTML and PDF. Please read Documentation/admin-guide/README.rst first.
In order to build the documentation, use ``make htmldocs`` or ``make pdfdocs``. The formatted documentation can also be read online at:
https://www.kernel.org/doc/html/latest/
There are various text files in the Documentation/ subdirectory, several of them using the Restructured Text markup notation.
Please read the Documentation/process/changes.rst file, as it contains the requirements for building and running the kernel, and information about the problems which may result by upgrading your kernel.
__Useful links__
* [Linux kernel licensing rules](https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing)
* [Reporting bugs](https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html)
--fix
option enabled
The text processed with # Linux kernel
There are several guides for kernel developers and users. These guides can be
rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.
In order to build the documentation, use `make htmldocs` or `make pdfdocs`. The
formatted documentation can also be read online at:
```
https://www.kernel.org/doc/html/latest/
```
There are various text files in the Documentation/ subdirectory, several of them
using the Restructured Text markup notation.
Please read the Documentation/process/changes.rst file, as it contains the
requirements for building and running the kernel, and information about the
problems which may result by upgrading your kernel.
**Useful links**
- [Linux kernel licensing rules](https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing)
- [Reporting bugs](https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html)
Credits
Shiny picture for the project was made by Igor Garybaldi.