remarkjs/remark-lint
1
1
Fork 0
mirror of https://github.com/remarkjs/remark-lint.git synced 2024-10-26 19:31:42 +03:00
Code Issues Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Titus Wormer 2016-06-13 17:02:19 +02:00
parent 8aa2d2c678
commit 149a4a1b7c
5 changed files with 114 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.remarkrc
View File

@ -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
View File

@ -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.

0
doc/comparison/markdownlint.md → doc/comparison-to-markdownlint.md
View File

1
doc/rules.md
View File

@ -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
View File

@ -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