@ariiera/remark-lint-styleguide v1.0.1

@ariiera/remark-lint-styleguide

Personalized remark-lint styleguide preset.

Installation and Usage

Local installation

If you want to lint the Markdown files from a project, the recommended way is to install this package as a development dependency via npm. Requires remark-cli.

npm install --save-dev remark-cli @ariiera/remark-lint-styleguide

Then, add the remarkConfig field in your package.json file.

"remarkConfig": {
  "plugins": [
    "@ariiera/remark-lint-styleguide"
  ]
}

Alternatively, you can create a .remarkrc file in the root of your project and put the configuration there.

{
  "plugins": [
    "@ariiera/remark-lint-styleguide"
  ]
}

Next, you need to setup a npm script to lint Markdown files. See the remark-cli package for more information on all available options.

"scripts": {
  "lint-md": "remark ."
}

Run the script from the command-line.

npm run lint-md

You can tell remark to ignore certain files or folders by creating a .remarkignore file in the root of your project. The format is the same as for .gitignore files.

Alternatively, you can use any file that follows the standard ignore file format. You can even use your .gitignore file.

"scripts": {
  "lint-md": "remark --ignore-path .gitignore ."
}

Programmatic usage

If you want to lint Markdown inside a Node.js module, you need to install this package as a project dependency via npm. Requires remark.

npm install --save remark @ariiera/remark-lint-styleguide vfile-reporter

If you want to use it inside your project's custom build script, you should install this package as a development dependency via npm. Requires remark.

npm install --save-dev remark @ariiera/remark-lint-styleguide vfile-reporter

Quick example:

const fs = require('fs');
const remark = require('remark');
const styleguide = require('@ariiera/remark-lint-styleguide');
const report = require('vfile-reporter');

const myFile = fs.readFileSync('my-awesome-article.md', 'utf8');

let output = remark().use(styleguide).processSync(myFile);

console.log(report(output));

The remark package interface is provided by the unified package. See the documentation of both projects in order to get a better understanding of the API.

Configuration

Each rule can be configured with a severity level:

• off: turn the rule off
• warn: show a warning for problems (exit code is 0, lint passes). Used by optional rules that might have a valid edge case.
• error: trigger an error for problems (exit code is 1, lint fails). Used by rules that enforce correct syntax, best practices or portability.

Override rules

Start your configuration with one of the presets and then modify certain rules to better suit your needs.

"remarkConfig": {
  "plugins": [
    "@ariiera/remark-lint-styleguide",
    ["remark-lint-no-html", false]
  ]
}

Configuration comments

You can use configuration comments to turn all or certain rules on or off inside a file. Note that you cannot change their setting, only whether messages for that rule are shown or hidden. See the remark-message-control package for more information.

To disable all remark-lint rules for an entire file, put the comment at the top of the file.

<!-- lint disable -->

# Heading

Paragraph.

* list item 1
* list item 2
* list item 3

Disable certain rules for an entire file.

<!-- lint disable no-html unordered-list-marker-style -->

# Heading

<img src="cover.png">

Paragraph.

* list item 1
* list item 2
* list item 3

Disable certain rules only for a section of text.

# Heading

<!-- lint disable no-html unordered-list-marker-style -->

<img src="cover.png">

* list item 1
* list item 2
* list item 3

<!-- lint enable no-html unordered-list-marker-style -->

Paragraph.

- list item 1
- list item 2
- list item 3

Disable certain rules only for the next node.

# Heading

<!-- lint ignore no-html -->

<img src="cover.png">

Paragraph.

- list item 1
- list item 2
- list item 3

Note: You'll need the blank lines between comments and other nodes!

External rules

In order to use the "external rules" you will first have to install their respective package and then add them to your configuration. Example: remark-lint-no-url-trailing-slash.

First, install the rule as a development dependency.

npm install --save-dev remark-lint-no-url-trailing-slash

Then, add the rule to your existing configuration and provide a severity level for it.

"remarkConfig": {
  "plugins": [
    "@ariiera/remark-lint-styleguide",
    ["remark-lint-no-url-trailing-slash", ["warn"]]
  ]
}

Help

If you have questions that this document or the remark and remark-lint documentations do not answer, please use the official Gitter chat room for remark.

Issues

Use this project's issue tracker for any of these situations:

• report a preset that does not correctly implement the style guide it is based on
• request a new preset
• other aspects directly related to the current package

For problems related to the remark and remark-lint packages, please use their respective issue trackers.

Authors

• Noah Vazquez - Initial work - ariiiera

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Thank you to raduserbanescu for the bulk of information in this readme