From 149a4a1b7cff88cb6cf5e12e992ccccb774a2abb Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 13 Jun 2016 17:02:19 +0200 Subject: [PATCH] Update docs --- .remarkrc | 18 +- doc/api.md | 72 -------- ...nlint.md => comparison-to-markdownlint.md} | 0 doc/rules.md | 1 - readme.md | 172 +++++++++++------- 5 files changed, 114 insertions(+), 149 deletions(-) delete mode 100644 doc/api.md rename doc/{comparison/markdownlint.md => comparison-to-markdownlint.md} (100%) diff --git a/.remarkrc b/.remarkrc index d6306023..78a67c30 100644 --- a/.remarkrc +++ b/.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": "*" } diff --git a/doc/api.md b/doc/api.md deleted file mode 100644 index 97ee7cfa..00000000 --- a/doc/api.md +++ /dev/null @@ -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. diff --git a/doc/comparison/markdownlint.md b/doc/comparison-to-markdownlint.md similarity index 100% rename from doc/comparison/markdownlint.md rename to doc/comparison-to-markdownlint.md diff --git a/doc/rules.md b/doc/rules.md index 84bcd94d..78a237fb 100644 --- a/doc/rules.md +++ b/doc/rules.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) diff --git a/readme.md b/readme.md index bfb8b24a..53a1cdab 100644 --- a/readme.md +++ b/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] + + **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 + + 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-` -[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