remark-lint

What is remark-lint?

remark-lint is a plugin for remark, a Markdown processor powered by plugins. It provides a framework for analyzing and reporting on Markdown code quality issues, ensuring consistency and adherence to specified style guidelines.

What are remark-lint's main functionalities?

Linting Markdown Files

This feature allows you to lint Markdown files to ensure they adhere to specified style guidelines. The code sample demonstrates how to use remark-lint to process a simple Markdown string and report any issues.

const remark = require('remark');
const lint = require('remark-lint');

remark()
  .use(lint)
  .process('# Hello world!', function (err, file) {
    console.error(report(err || file));
  });

Custom Rules

remark-lint supports custom rules, allowing you to enforce specific style guidelines. The code sample shows how to use a custom rule (remark-lint-no-emphasis-as-heading) to lint a Markdown string.

const remark = require('remark');
const lint = require('remark-lint');
const noEmphasisAsHeading = require('remark-lint-no-emphasis-as-heading');

remark()
  .use(lint)
  .use(noEmphasisAsHeading)
  .process('# Hello *world*!', function (err, file) {
    console.error(report(err || file));
  });

Configurable Presets

remark-lint provides configurable presets that bundle multiple rules together for convenience. The code sample demonstrates how to use the 'remark-preset-lint-recommended' preset to lint a Markdown string.

const remark = require('remark');
const lint = require('remark-lint');
const presetLintRecommended = require('remark-preset-lint-recommended');

remark()
  .use(lint)
  .use(presetLintRecommended)
  .process('# Hello world!', function (err, file) {
    console.error(report(err || file));
  });

Other packages similar to remark-lint

markdownlint

markdownlint is a Node.js style checker and lint tool for Markdown files. It provides a set of rules to enforce consistent Markdown style and can be customized with configuration files. Compared to remark-lint, markdownlint is more focused on providing a comprehensive set of built-in rules and is often used as a standalone tool.

markdown-it

markdown-it is a Markdown parser that can be extended with plugins to add custom functionality, including linting. While markdown-it is primarily a parser, it can be combined with plugins to achieve similar linting capabilities as remark-lint. However, it is more flexible and less opinionated about style rules.

textlint

textlint is a text linting framework that supports multiple file formats, including Markdown. It allows users to define custom rules and plugins to enforce style guidelines. textlint is more versatile than remark-lint, as it can be used to lint various types of text files, not just Markdown.

README

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, but the defaults are sensible :ok_hand:.

remark-lint is built on remark, a powerful markdown processor powered by plugins (such as this one).

Table of Contents

• Installation
• Command line
• Programmatic
  • remark.use(lint[, options])
• Rules
• Configuring remark-lint
• Using remark to fix your markdown
• Editor Integrations
• List of External Rules
• Related
• License

Installation

npm:

npm install remark-lint

remark-lint is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.

Command line

Use remark-lint together with remark-cli:

npm install --global remark-cli remark-lint

Let’s say example.md looks as follows:

* Hello

[World][]

Now, running 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

See doc/rules.md for what those warnings are (and how to turn them off).

Programmatic

Use remark-lint together with remark:

npm install remark remark-lint

Let’s say example.js looks as follows:

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:

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

When processing a file, these warnings are available at file.messages, and look as follows:

{
  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 for more information.

Rules

doc/rules.md describes all available rules, what they check for, examples of markdown they warn for, and how to fix their warnings.

Configuring remark-lint

remark-lint is a remark plug-in and supports configuration through its configuration files.

An example .remarkrc file could look as follows:

{
  "plugins": {
    "remark-lint": {
      "no-multiple-toplevel-headings": false,
      "list-item-indent": false,
      "maximum-line-length": 79
    }
  }
}

Where the object at plugins['remark-lint'] is a map of ruleIds and their values.

Using our example.md from before:

* Hello

[World][]

Now, running remark example.md (without -u remark-lint since our .remarkrc includes the lint plugin) yields:

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, just whether they are shown or not. Read more about configuration comments in remark-message-controls documentation.

The following file will warn twice for the duplicate headings:

# Hello

## Hello

### Hello

The following file will warn once (the second heading is ignored, but the third is re-enabled):

# Hello

<!--lint disable no-duplicate-headings-->

## Hello

<!--lint enable no-duplicate-headings-->

### Hello

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, emphasis and strong use a standard marker, and that your table fences are aligned.

remark should be able to fix most of your styling issues automatically, and I strongly suggest checking out how it can make your life easier :+1:

Editor Integrations

Currently, remark-lint is integrated with Atom through linter-markdown.

I’m very interested in more integrations. Let me know if I can help.

List of External Rules

• vhf/remark-lint-alphabetize-lists — Ensure list items are in alphabetical order;
• vhf/remark-lint-blank-lines-1-0-2 — Ensure a specific number of lines between blocks;
• vhf/remark-lint-books-links — Ensure links in lists of books follow a standard format;
• Qard/remark-lint-code — Lint fenced code blocks by corresponding language tags, currently supporting ESLint.
• vhf/remark-lint-no-empty-sections — Ensure every heading is followed by content (forming a section);
• chcokr/remark-lint-sentence-newline — Ensure sentences are followed by a newline;
• vhf/remark-lint-no-url-trailing-slash — Ensure that the href of links has no trailing slash.

Related

• wooorm/remark-validate-links — Validate if links point to existing headings and files in markdown.

License

MIT © Titus Wormer