mirror of
https://github.com/remarkjs/remark-lint.git
synced 2024-10-26 19:31:42 +03:00
Update docs
This commit is contained in:
parent
8aa2d2c678
commit
149a4a1b7c
18
.remarkrc
18
.remarkrc
@ -1,12 +1,16 @@
|
||||
{
|
||||
"output": true,
|
||||
"plugins": [
|
||||
"comment-config",
|
||||
"github",
|
||||
"toc",
|
||||
"./",
|
||||
"validate-links"
|
||||
],
|
||||
"plugins": {
|
||||
"comment-config": null,
|
||||
"github": null,
|
||||
"toc": {
|
||||
"tight": true
|
||||
},
|
||||
"./": {
|
||||
"no-missing-blank-lines": false
|
||||
},
|
||||
"validate-links": null
|
||||
},
|
||||
"settings": {
|
||||
"bullet": "*"
|
||||
}
|
||||
|
72
doc/api.md
72
doc/api.md
@ -1,72 +0,0 @@
|
||||
# API
|
||||
|
||||
## Usage
|
||||
|
||||
Dependencies:
|
||||
|
||||
```javascript
|
||||
var remark = require('remark');
|
||||
var lint = require('remark-lint');
|
||||
var processor = remark().use(lint);
|
||||
```
|
||||
|
||||
Example document.
|
||||
|
||||
```javascript
|
||||
var doc = '* Hello\n' +
|
||||
'\n' +
|
||||
'- World\n';
|
||||
```
|
||||
|
||||
Process.
|
||||
|
||||
```javascript
|
||||
processor.process(doc, function (err, file, res) {
|
||||
var messages = file.messages;
|
||||
/**
|
||||
* Yields:
|
||||
* [
|
||||
* {
|
||||
* "name": "1:3-1:8",
|
||||
* "file": "",
|
||||
* "reason": "Incorrect list-item content indent: add 2 spaces",
|
||||
* "line": 1,
|
||||
* "column": 3,
|
||||
* "fatal": false,
|
||||
* "ruleId": "list-item-indent"
|
||||
* },
|
||||
* {
|
||||
* "name": "3:1-3:10",
|
||||
* "file": "",
|
||||
* "reason": "Invalid ordered list item marker: should be `*`",
|
||||
* "line": 3,
|
||||
* "column": 1,
|
||||
* "fatal": false,
|
||||
* "ruleId": "unordered-list-marker-style"
|
||||
* }
|
||||
* ]
|
||||
*/
|
||||
});
|
||||
```
|
||||
|
||||
## [remark](https://github.com/wooorm/remark#api).[use](https://github.com/wooorm/remark#remarkuseplugin-options)(lint, options)
|
||||
|
||||
Adds warnings for style violations to a given [virtual file](https://github.com/wooorm/remark/blob/master/doc/remark.3.md#file)
|
||||
using remark’s [warning API](https://github.com/wooorm/remark/blob/master/doc/remark.3.md#filewarnreason-position).
|
||||
|
||||
When processing a file, these warnings are available at `file.messages`, and
|
||||
look as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"fatal": false,
|
||||
"reason": "Marker style should be `*`",
|
||||
"file": "~/example.md",
|
||||
"line": 3,
|
||||
"column": 1,
|
||||
"ruleId": "unordered-list-marker-style"
|
||||
}
|
||||
```
|
||||
|
||||
See [`VFileMessage`](https://github.com/wooorm/vfile#vfilemessage) for more
|
||||
information.
|
@ -9,7 +9,6 @@ See the readme for a [list of external rules](https://github.com/wooorm/remark-l
|
||||
## Table of Contents
|
||||
|
||||
* [Rules](#rules)
|
||||
|
||||
* [external](#external)
|
||||
* [reset](#reset)
|
||||
* [blockquote-indentation](#blockquote-indentation)
|
||||
|
172
readme.md
172
readme.md
@ -1,24 +1,26 @@
|
||||
# ![remark-lint][logo]
|
||||
|
||||
[![Build Status][travis-badge]][travis-ci]
|
||||
[![Coverage Status][coverage-badge]][coverage-ci]
|
||||
[![Build Status][build-badge]][build-status]
|
||||
[![Coverage Status][coverage-badge]][coverage-status]
|
||||
[![Chat][chat-badge]][chat]
|
||||
|
||||
<!--lint disable list-item-spacing-->
|
||||
|
||||
**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,
|
||||
sure less refactoring is needed afterwards. What is quality? That’s up to you,
|
||||
but the defaults are sensible :ok_hand:.
|
||||
|
||||
**remark-lint** has lots of tests. Supports Node, io.js, and the browser.
|
||||
100% coverage. 50+ rules. It’s built on [**remark**][remark],
|
||||
a powerful markdown processor powered by [plugins][remark-plugins]
|
||||
(such as this one).
|
||||
**remark-lint** is built on [**remark**][remark], a powerful markdown
|
||||
processor powered by [plugins][remark-plugins] (such as this one).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Installation](#installation)
|
||||
* [Command line](#command-line)
|
||||
* [Programmatic](#programmatic)
|
||||
* [remark.use(lint\[, options\])](#remarkuselint-options)
|
||||
* [Rules](#rules)
|
||||
* [Configuring remark-lint](#configuring-remark-lint)
|
||||
* [Using remark to fix your markdown](#using-remark-to-fix-your-markdown)
|
||||
@ -29,7 +31,7 @@ a powerful markdown processor powered by [plugins][remark-plugins]
|
||||
|
||||
## Installation
|
||||
|
||||
[npm][npm-install]:
|
||||
[npm][]:
|
||||
|
||||
```bash
|
||||
npm install remark-lint
|
||||
@ -42,10 +44,10 @@ module, [uncompressed and compressed][releases].
|
||||
|
||||
![Example of how remark-lint looks on screen][screenshot]
|
||||
|
||||
Use remark-lint together with remark:
|
||||
Use `remark-lint` together with [`remark-cli`][cli]:
|
||||
|
||||
```bash
|
||||
npm install --global remark remark-lint
|
||||
npm install --global remark-cli remark-lint
|
||||
```
|
||||
|
||||
Let’s say `example.md` looks as follows:
|
||||
@ -56,18 +58,13 @@ Let’s say `example.md` looks as follows:
|
||||
[World][]
|
||||
```
|
||||
|
||||
Then, to run **remark-lint** on `example.md`:
|
||||
Now, running `remark example.md -u remark-lint` yields:
|
||||
|
||||
```bash
|
||||
remark example.md -u remark-lint
|
||||
#
|
||||
# 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
|
||||
```txt
|
||||
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`][rules] for what those warnings are (and how to
|
||||
@ -75,8 +72,55 @@ turn them off).
|
||||
|
||||
## Programmatic
|
||||
|
||||
[`doc/api.md`][api] describes how to use **remark-lint**’s
|
||||
programatic interface in JavaScript.
|
||||
Use `remark-lint` together with [`remark`][api]:
|
||||
|
||||
```bash
|
||||
npm install remark remark-lint
|
||||
```
|
||||
|
||||
Let’s say `example.js` looks as follows:
|
||||
|
||||
```js
|
||||
var report = require('vfile-reporter');
|
||||
var remark = require('remark');
|
||||
var lint = require('remark-lint');
|
||||
|
||||
var file = remark().use(lint).process('## Hello world!');
|
||||
|
||||
console.log(report(file));
|
||||
```
|
||||
|
||||
Now, running `node example.js` yields:
|
||||
|
||||
```txt
|
||||
<stdin>
|
||||
1:1 warning Missing newline character at end of file final-newline
|
||||
1:1-1:16 warning First heading level should be `1` first-heading-level
|
||||
1:1-1:16 warning Don’t add a trailing `!` to headings no-heading-punctuation
|
||||
|
||||
⚠ 3 warnings
|
||||
```
|
||||
|
||||
### `remark.use(lint[, options])`
|
||||
|
||||
Adds warnings for style violations to the processed [virtual file][vfile].
|
||||
|
||||
When processing a file, these warnings are available at `file.messages`, and
|
||||
look as follows:
|
||||
|
||||
```js
|
||||
{
|
||||
file: '~/example.md',
|
||||
reason: 'First heading level should be `1`',
|
||||
line: 1,
|
||||
column: 1,
|
||||
location: Position { start: [Object], end: [Object] },
|
||||
ruleId: 'first-heading-level',
|
||||
fatal: false,
|
||||
source: 'remark-lint' }
|
||||
```
|
||||
|
||||
See [`VFileMessage`][vfile-message] for more information.
|
||||
|
||||
## Rules
|
||||
|
||||
@ -85,31 +129,25 @@ for, examples of markdown they warn for, and how to fix their warnings.
|
||||
|
||||
## Configuring remark-lint
|
||||
|
||||
**remark-lint** is just a **remark** plug-in. Meaning, you can opt to
|
||||
configure using configuration files. Read more about these files
|
||||
(`.remarkrc` or `package.json`) in [**remark**’s docs][remarkrc].
|
||||
**remark-lint** is a **remark** plug-in and supports configuration
|
||||
through its [configuration files][cli].
|
||||
|
||||
An example `.remarkrc` file could look as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"lint": {
|
||||
"remark-lint": {
|
||||
"no-multiple-toplevel-headings": false,
|
||||
"list-item-indent": false,
|
||||
"maximum-line-length": 79
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"commonmark": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Where the object at `plugins.lint` is a map of `ruleId`s and their values. The
|
||||
object at `settings` determines how **remark** parses (and compiles)
|
||||
markdown code. Read more about the latter on
|
||||
[**remark**’s readme][remark-process].
|
||||
Where the object at `plugins['remark-lint']` is a map of `ruleId`s and
|
||||
their values.
|
||||
|
||||
Using our `example.md` from before:
|
||||
|
||||
@ -119,24 +157,20 @@ Using our `example.md` from before:
|
||||
[World][]
|
||||
```
|
||||
|
||||
We now run the below command _without_ the `-u remark-lint` since
|
||||
our `.remarkrc` includes the lint plugin.
|
||||
Now, running `remark example.md` (**without `-u remark-lint`** since
|
||||
our `.remarkrc` includes the lint plugin) yields:
|
||||
|
||||
```bash
|
||||
remark example.md
|
||||
#
|
||||
# Yields:
|
||||
#
|
||||
# example.md
|
||||
# 3:1-3:10 warning Found reference to undefined definition no-undefined-references
|
||||
#
|
||||
# ⚠ 2 warnings
|
||||
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`, checks for, as you’re either enabling
|
||||
or disabling warnings). Read more about configuration comments in
|
||||
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-control**][message-control]s documentation.
|
||||
|
||||
The following file will warn twice for the duplicate headings:
|
||||
@ -167,7 +201,7 @@ but the third is re-enabled):
|
||||
## 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,
|
||||
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.
|
||||
|
||||
@ -179,7 +213,7 @@ and I strongly suggest checking out how it can make your life easier :+1:
|
||||
Currently, **remark-lint** is integrated with Atom through
|
||||
[**linter-markdown**][linter-markdown].
|
||||
|
||||
I’m very interested in more integrations. Let me know if I can help.
|
||||
I’m very interested in more integrations. Let me know if I can help.
|
||||
|
||||
## List of External Rules
|
||||
|
||||
@ -190,23 +224,17 @@ excluding `remark-lint-no-` or `remark-lint-`
|
||||
|
||||
* [`vhf/remark-lint-alphabetize-lists`](https://github.com/vhf/remark-lint-alphabetize-lists)
|
||||
— Ensure list items are in alphabetical order;
|
||||
|
||||
* [`vhf/remark-lint-blank-lines-1-0-2`](https://github.com/vhf/remark-lint-blank-lines-1-0-2)
|
||||
— Ensure a specific number of lines between blocks;
|
||||
|
||||
* [`vhf/remark-lint-books-links`](https://github.com/vhf/remark-lint-books-links)
|
||||
— Ensure links in lists of books follow a standard format;
|
||||
|
||||
* [`Qard/remark-lint-code`](https://github.com/Qard/remark-lint-code)
|
||||
— Lint fenced code blocks by corresponding language tags,
|
||||
currently supporting [ESLint](https://github.com/Qard/remark-lint-code-eslint).
|
||||
|
||||
* [`vhf/remark-lint-no-empty-sections`](https://github.com/vhf/remark-lint-no-empty-sections)
|
||||
— Ensure every heading is followed by content (forming a section);
|
||||
|
||||
* [`chcokr/remark-lint-sentence-newline`](https://github.com/chcokr/remark-lint-sentence-newline)
|
||||
— Ensure sentences are followed by a newline;
|
||||
|
||||
* [`vhf/remark-lint-no-url-trailing-slash`](https://github.com/vhf/remark-lint-no-url-trailing-slash)
|
||||
— Ensure that the `href` of links has no trailing slash.
|
||||
|
||||
@ -221,38 +249,44 @@ excluding `remark-lint-no-` or `remark-lint-`
|
||||
|
||||
<!-- Definitions -->
|
||||
|
||||
[travis-badge]: https://img.shields.io/travis/wooorm/remark-lint.svg
|
||||
[build-badge]: https://img.shields.io/travis/wooorm/remark-inline-links.svg
|
||||
|
||||
[travis-ci]: https://travis-ci.org/wooorm/remark-lint
|
||||
[build-status]: https://travis-ci.org/wooorm/remark-inline-links
|
||||
|
||||
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark-lint.svg
|
||||
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark-inline-links.svg
|
||||
|
||||
[coverage-ci]: https://codecov.io/github/wooorm/remark-lint
|
||||
[coverage-status]: https://codecov.io/github/wooorm/remark-inline-links
|
||||
|
||||
[npm-install]: https://docs.npmjs.com/cli/install
|
||||
[chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
|
||||
|
||||
[releases]: https://github.com/wooorm/remark-lint/releases
|
||||
[chat]: https://gitter.im/wooorm/remark
|
||||
|
||||
[releases]: https://github.com/wooorm/remark-inline-links/releases
|
||||
|
||||
[license]: LICENSE
|
||||
|
||||
[author]: http://wooorm.com
|
||||
|
||||
[npm]: https://docs.npmjs.com/cli/install
|
||||
|
||||
[remark]: https://github.com/wooorm/remark
|
||||
|
||||
[logo]: https://cdn.rawgit.com/wooorm/remark-lint/master/logo.svg
|
||||
|
||||
[screenshot]: https://cdn.rawgit.com/wooorm/remark-lint/master/screenshot.png
|
||||
|
||||
[rules]: doc/rules.md
|
||||
|
||||
[api]: doc/api.md
|
||||
[api]: https://github.com/wooorm/remark/tree/master/packages/remark
|
||||
|
||||
[license]: LICENSE
|
||||
|
||||
[remark]: https://github.com/wooorm/remark
|
||||
[cli]: https://github.com/wooorm/remark/tree/master/packages/remark-cli
|
||||
|
||||
[remark-plugins]: https://github.com/wooorm/remark/blob/master/doc/plugins.md
|
||||
|
||||
[remarkrc]: https://github.com/wooorm/remark/blob/master/doc/remarkrc.5.md
|
||||
|
||||
[remark-process]: https://github.com/wooorm/remark#remarkprocessvalue-options-done
|
||||
|
||||
[linter-markdown]: https://atom.io/packages/linter-markdown
|
||||
|
||||
[message-control]: https://github.com/wooorm/remark-message-control#markers
|
||||
|
||||
[vfile]: https://github.com/wooorm/vfile
|
||||
|
||||
[vfile-message]: https://github.com/wooorm/vfile#vfilemessage
|
||||
|
Loading…
Reference in New Issue
Block a user