CI/CD & Pipeline Integration

Integrating markdownlint-cli into your development workflows and automated pipelines ensures that all repository documents remain formatted correctly before they are merged.

---

Integration via pre-commit

pre-commit is a popular framework for managing and maintaining multi-language Git pre-commit hooks. markdownlint-cli features built-in pre-commit hooks to validate your files locally prior to commit.

Add the following configuration to your project's .pre-commit-config.yaml file:

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

Available Hook Configurations:

• markdownlint: Inspects staging-area Markdown files and reports formatting errors without modifying files.
• markdownlint-fix: Inspects files, applies automatable fixes in-place, and updates files before committing.
• markdownlint-docker: Executes linting checks inside a container using the official Docker image. (This is useful if Node is not installed locally on your system).
• markdownlint-fix-docker: Automatically corrects formatting violations inside a container environment.

---

Integrating with GitHub Actions

You can configure the linter to run as a validation step inside GitHub Actions. Below is a complete, production-ready workflow configuration (.github/workflows/lint.yml):

name: Style Validation

on:
  push:
    branches:
      - master
      - main
  pull_request:
    branches:
      - master
      - main

permissions:
  contents: read

jobs:
  markdownlint:
    name: Validate Markdown Style
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Source Code
        uses: actions/checkout@v6

      - name: Setup Node.js Runtime
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm

      - name: Install Project Dependencies
        run: npm ci

      - name: Run Markdown Lint Verification
        run: npx markdownlint '**/*.md' --ignore node_modules

---

Containerized Executions with Docker

For continuous integration environments that run actions within standalone Docker container runners (such as GitLab CI, Jenkins, or Drone), run the official Alpine-based Node runtime image:

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

Configuration Options for GitLab CI (.gitlab-ci.yml):

stages:
  - test

markdown_style_check:
  stage: test
  image:
    name: ghcr.io/igorshubovych/markdownlint-cli:v0.47.0
    entrypoint: [""]
  script:
    - /usr/local/bin/markdownlint '**/*.md' --ignore node_modules

---

Handling exit codes in CI/CD pipelines

When writing automated scripts for your pipelines, remember that the CLI returns specific exit codes depending on the result of the linting run:

• Exit Code 0: No formatting errors occurred. The pipeline continues to the next step.
• Exit Code 1: Formatting errors were found. The step fails, and the pipeline halts.
• Exit Codes 2, 3, 4: Failures due to configuration errors or invalid paths. This indicates a setup issue that needs attention.