Installation and Setup

markdownlint-cli is written in JavaScript and runs on Node.js runtimes. This guide details setup procedures across local development machines, system packages, and Docker containers.

Node.js Engine Requirements

  • Node.js Version: Requires Node.js v20 or newer.
  • Strict Engines: In environments enforcing explicit package requirements, markdownlint-cli respects strict engine parameters, as defined in its workspace .npmrc file (engine-strict=true).

Installation Pathways

For team-based software and documentation repositories, install markdownlint-cli locally. Managing dependency versions at the project level guarantees that all team members and CI pipelines execute the exact same linter ruleset, avoiding configuration conflicts.

Install the package into your project workspace:

npm install --save-dev markdownlint-cli

Once installed locally, execute commands using npx:

npx markdownlint --version

Alternatively, register a script task in your project's package.json file:

{
  "name": "my-project",
  "scripts": {
    "lint:docs": "markdownlint \"docs/**/*.md\""
  },
  "devDependencies": {
    "markdownlint-cli": "^0.47.0"
  }
}

Run the workspace command using your preferred package manager:

npm run lint:docs
# or
yarn lint:docs
# or
pnpm lint:docs

2. Global Installation

If you are a technical writer managing documentation across multiple independent repositories, install the tool globally on your system to access the binary from any terminal session:

npm install -g markdownlint-cli

Ensure that your global Node directory is mapped within your system $PATH environment variables to access the CLI directly:

markdownlint --help

3. Homebrew (macOS and Linux)

If you manage command-line applications outside of Node workspaces, install markdownlint-cli using Homebrew. This is highly useful for team members who do not actively write JavaScript:

brew install markdownlint-cli

4. Running via Docker

To perform validation runs without installing Node.js globally on host servers, run the official container image distributed through GitHub Container Registry (ghcr.io). This image is based on lightweight Linux distributions (Alpine):

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

Key Run Settings:

  • --rm: Automatically destroys the temporary runtime container once validation finishes.
  • -v "$PWD":/workdir: Mounts the host workspace directory to the container's designated /workdir workspace, so files can be analyzed locally.

Troubleshooting Common Installation Failures

Permission Denied (EACCES Errors during global installs)

This occurs when global NPM folders are configured with root administrative ownership. You can resolve this issue by running the command with root user privileges (not recommended), using a Node Version Manager (nvm), or configuring custom user-owned directories.

Quick path configuration adjustments: 

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
source ~/.bashrc
Then reinstall without sudo: 
npm install -g markdownlint-cli

Node.js Engine Mismatch Error

If you run on deprecated Node.js platforms (e.g. Node 18, 16, or older) and engine validations are enforced locally, installation fails with an engine error. Update your local runtime environment via nvm: 

nvm install 22
nvm use 22

Verify Your Environment

To ensure your active binary environment maps correctly to the CLI and matches system parameters, execute:

markdownlint --version

Proceed to the Quick Start Guide to perform your first validation scan.