markdownlint-cli

MarkdownLint Command Line Interface

1,031

100

1,031

View on GitHub View on NPM

Top Related Projects

remark-lint

1,026

plugins to check (lint) markdown code style

Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.

markdown-it

21,185

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed

Quick Overview

Error generating quick overview

Competitor Comparisons

markdownlint

1,994

Markdown lint tool

Pros of markdownlint

Written in Ruby, which may be preferred by some developers
Longer development history and potentially more mature codebase
Offers a wider range of configuration options

Cons of markdownlint

Slower performance compared to the Node.js-based alternative
Less frequent updates and potentially fewer contributors
May require additional setup for Ruby environment

Code Comparison

markdownlint:

MDLint.run(["some_file.md"]) do |err|
  puts "#{err.filename}: #{err.line} - #{err.rule.description}"
end

markdownlint-cli:

const markdownlint = require("markdownlint");
const options = {
  files: ["some_file.md"],
  config: { default: true }
};
markdownlint(options, (err, result) => {
  console.log(result.toString());
});

Both projects aim to provide linting for Markdown files, but they differ in implementation language and usage patterns. markdownlint offers a Ruby-based solution with extensive configuration options, while markdownlint-cli provides a faster, Node.js-based alternative with simpler setup and integration. The choice between the two may depend on your project's tech stack, performance requirements, and desired level of customization.

remark-lint

1,026

plugins to check (lint) markdown code style

Pros of remark-lint

Part of a larger ecosystem (remark) for processing markdown
More extensible with plugins and custom rules
Better support for modern JavaScript environments (ES modules)

Cons of remark-lint

Steeper learning curve due to its plugin-based architecture
Less out-of-the-box functionality compared to markdownlint-cli
Configuration can be more complex for simple use cases

Code Comparison

remark-lint:

import { remark } from 'remark';
import remarkLint from 'remark-lint';
import remarkPresetLintConsistent from 'remark-preset-lint-consistent';

remark()
  .use(remarkLint)
  .use(remarkPresetLintConsistent)
  .process('Your markdown here');

markdownlint-cli:

const markdownlint = require("markdownlint");

const options = {
  files: ["README.md"],
  config: {
    "default": true,
    "MD013": false
  }
};

markdownlint(options, function callback(err, result) {
  console.log(result.toString());
});

Both tools offer powerful markdown linting capabilities, but remark-lint is more flexible and extensible, while markdownlint-cli provides a simpler, more straightforward approach for basic linting needs. The choice between them depends on the specific requirements of your project and your familiarity with the remark ecosystem.

remarkable

5,825

Pros of Remarkable

Faster parsing and rendering of Markdown
More extensible with plugins and custom rules
Supports CommonMark specification

Cons of Remarkable

Less focused on linting and style checking
May require additional configuration for specific use cases
Not actively maintained (last commit over 3 years ago)

Code Comparison

Remarkable usage:

var Remarkable = require('remarkable');
var md = new Remarkable();
console.log(md.render('# Hello, world!'));

markdownlint-cli usage:

const markdownlint = require("markdownlint");
const options = {
  files: ["README.md"],
  config: { default: true }
};
markdownlint(options, function callback(err, result) {
  console.log(result.toString());
});

While Remarkable focuses on parsing and rendering Markdown, markdownlint-cli is specifically designed for linting and style checking Markdown files. Remarkable offers more flexibility in terms of customization and performance, but markdownlint-cli provides a more specialized tool for ensuring consistent Markdown formatting across projects.

markdown-it

21,185

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed

Pros of markdown-it

More versatile: Can be used for parsing, rendering, and manipulating Markdown
Extensible: Supports plugins for custom syntax and features
Faster performance for parsing and rendering large documents

Cons of markdown-it

Not specifically designed for linting Markdown files
Requires more setup and configuration for linting purposes
Less focused on enforcing consistent Markdown style

Code Comparison

markdownlint-cli:

const options = {
  files: ['**/*.md'],
  ignoreFiles: ['.git/**'],
  config: '.markdownlint.json'
};
markdownlint(options, (err, result) => {
  console.log(result.toString());
});

markdown-it:

const md = require('markdown-it')();
const result = md.render('# Markdown text');
console.log(result);

The code snippets demonstrate the primary use cases for each tool. markdownlint-cli is focused on linting Markdown files, while markdown-it is primarily used for parsing and rendering Markdown content. markdownlint-cli provides a more straightforward approach to enforcing Markdown style guidelines, whereas markdown-it offers greater flexibility for working with Markdown in various ways.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

markdownlint-cli

Command Line Interface for MarkdownLint

Installation

npm install -g markdownlint-cli

On macOS you can install via Homebrew:

brew install markdownlint-cli

Usage

markdownlint --help

  Usage: markdownlint [options] <files|directories|globs>

  MarkdownLint Command Line Interface

  Options:
    -V, --version                              output the version number
    -c, --config <configFile>                  configuration file (JSON, JSONC, JS, YAML, or TOML)
    --configPointer <pointer>                  JSON Pointer to object within configuration file (default: "")
    -d, --dot                                  include files/folders with a dot (for example `.github`)
    -f, --fix                                  fix basic errors (does not work with STDIN)
    -i, --ignore <file|directory|glob>         file(s) to ignore/exclude (default: [])
    -j, --json                                 write issues in json format
    -o, --output <outputFile>                  write issues to file (no console)
    -p, --ignore-path <file>                   path to file with ignore pattern(s)
    -q, --quiet                                do not write issues to STDOUT
    -r, --rules <file|directory|glob|package>  include custom rule files (default: [])
    -s, --stdin                                read from STDIN (does not work with files)
    --enable <rules...>                        Enable certain rules, e.g. --enable MD013 MD041 --
    --disable <rules...>                       Disable certain rules, e.g. --disable MD013 MD041 --
    -h, --help                                 display help for command

Or run using Docker and GitHub Packages:

docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "*.md"

Note Because --enable and --disable are variadic arguments that accept multiple values, it is necessary to end the list by passing -- before the <files|directories|globs> argument like so: markdownlint --disable MD013 -- README.md.

Globbing

markdownlint-cli supports advanced globbing patterns like **/*.md (more information). With shells like Bash, it may be necessary to quote globs so they are not interpreted by the shell. For example, --ignore *.md would be expanded by Bash to --ignore a.md b.md ... before invoking markdownlint-cli, causing it to ignore only the first file because --ignore takes a single parameter (though it can be used multiple times). Quoting the glob like --ignore '*.md' passes it through unexpanded and ignores the set of files.

Globbing examples

To lint all Markdown files in a Node.js project (excluding dependencies), the following commands might be used:

Windows CMD: markdownlint **/*.md --ignore node_modules

Linux Bash: markdownlint '**/*.md' --ignore node_modules

Ignoring files

If present in the current folder, a .markdownlintignore file will be used to ignore files and/or directories according to the rules for gitignore. If the -p/--ignore-path option is present, the specified file will be used instead of .markdownlintignore.

The order of operations is:

Enumerate files/directories/globs passed on the command line
Apply exclusions from -p/--ignore-path (if specified) or .markdownlintignore (if present)
Apply exclusions from any -i/--ignore option(s) that are specified

Fixing errors

When the --fix option is specified, markdownlint-cli tries to apply all fixes reported by the active rules and reports any errors that remain. Because this option makes changes to the input files, it is good to make a backup first or work with files under source control so any unwanted changes can be undone.

Because not all rules include fix information when reporting errors, fixes may overlap, and not all errors are fixable, --fix will not usually address all errors.

Configuration

markdownlint-cli reuses the rules from markdownlint package.

Configuration is stored in JSON, JSONC, YAML, INI, or TOML files in the same config format.

A sample configuration file:

{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}

For more examples, see .markdownlint.jsonc, .markdownlint.yaml, test-config.toml or the style folder.

The CLI argument --config is not required. If it is not provided, markdownlint-cli looks for the file .markdownlint.jsonc/.markdownlint.json/.markdownlint.yaml/.markdownlint.yml in current folder, or for the file .markdownlintrc in the current or all parent folders. The algorithm is described in detail on the rc package page. Note that when relying on the lookup of a file named .markdownlintrc in the current or parent folders, the only syntaxes accepted are INI and JSON, and the file cannot have an extension. If the --config argument is provided, the file must be valid JSON, JSONC, JS, or YAML. JS configuration files contain JavaScript code, must have the .js or .cjs file extension, and must export (via module.exports = ...) a configuration object of the form shown above. If your workspace (project) is ESM-only ("type": "module" set in the root package.json file), then the configuration file should end with .cjs file extension. A JS configuration file may internally require one or more npm packages as a way of reusing configuration across projects.

The --configPointer argument allows the use of JSON Pointer syntax to identify a sub-object within the configuration object (per above). This argument can be used with any configuration file type and makes it possible to nest a configuration object within another file like package.json or pyproject.toml (e.g., via /key or /key/subkey).

--enable and --disable override configuration files; if a configuration file disables MD123 and you pass --enable MD123, it will be enabled. If a rule is passed to both --enable and --disable, it will be disabled.

JS configuration files must be provided via the --config argument; they are not automatically loaded because running untrusted code is a security concern.

TOML configuration files must be provided via the --config argument; they are not automatically loaded.

Exit codes

markdownlint-cli returns one of the following exit codes:

0: Program ran successfully
1: Linting errors
2: Unable to write -o/--output output file
3: Unable to load -r/--rules custom rule
4: Unexpected error (e.g. malformed config)

Use with pre-commit

To run markdownlint-cli as part of a pre-commit workflow, add something like the below to the repos list in the project's .pre-commit-config.yaml:

- repo: https://github.com/igorshubovych/markdownlint-cli
  rev: v0.41.0
  hooks:
  - id: markdownlint

Depending on the environment this workflow runs in, it may be necessary to override the language version of Node.js used by pre-commit.

markdownlint - API for this module
markdownlint-cli2 - Alternate CLI implementation
glob - Pattern matching implementation
ignore - .markdownlintignore implementation

License

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Competitor Comparisons

Pros of markdownlint

Cons of markdownlint

Code Comparison

Pros of remark-lint

Cons of remark-lint

Code Comparison

Pros of Remarkable

Cons of Remarkable

Code Comparison

Pros of markdown-it

Cons of markdown-it

Code Comparison

Convert designs to code with AI

README

markdownlint-cli

Installation

Usage

Globbing

Globbing examples

Ignoring files

Fixing errors

Configuration

Exit codes

Use with pre-commit

Related

License

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days