Update docs

Author: wooorm

.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": "*"
   }

doc/api.md

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

doc/comparison/markdownlint.md doc/comparison-to-markdownlint.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,27 +58,69 @@ 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
 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
+
+[build-status]: https://travis-ci.org/wooorm/remark-inline-links
 
-[travis-ci]: https://travis-ci.org/wooorm/remark-lint
+[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark-inline-links.svg
 
-[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark-lint.svg
+[coverage-status]: https://codecov.io/github/wooorm/remark-inline-links
 
-[coverage-ci]: https://codecov.io/github/wooorm/remark-lint
+[chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
 
-[npm-install]: https://docs.npmjs.com/cli/install
+[chat]: https://gitter.im/wooorm/remark
 
-[releases]: https://github.com/wooorm/remark-lint/releases
+[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
-
-[license]: LICENSE
+[api]: https://github.com/wooorm/remark/tree/master/packages/remark
 
-[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