Guides

ESLint and oxlint

ESLint and oxlint check your code, and lint-comark checks your Markdown. Neither reads :: blocks, so add lint-comark to the same scripts instead of to their configs:

pnpm add -D comark-linter

{
  "scripts": {
    "lint": "eslint . && lint-comark \"content/**/*.md\""
  }
}

{
  "scripts": {
    "lint": "oxlint && lint-comark \"content/**/*.md\""
  }
}

Quote the glob so the shell passes it as it is; lint-comark expands it and skips node_modules and dist. pnpm lint now fails on a broken document the way it fails on a lint error in code:

content/review.md:8:1 comark/unclosed-block `::compare` opened on line 8 is never closed. Add a line with `::` after its last child.

If you use @eslint/markdown, keep it: it checks plain Markdown, and lint-comark checks what Comark adds on top.

Staged files

With lint-staged, each tool gets the staged files it understands. lint-comark takes file paths as well as globs:

{
  "lint-staged": {
    "*.{js,ts,vue}": "eslint --fix",
    "*.{md,mdc}": "lint-comark"
  }
}

Swap eslint --fix for oxlint --fix if that's your linter.

CI

pnpm lint exits with 1 on any problem, so a CI job needs only one step for both:

- run: pnpm install --frozen-lockfile
- run: pnpm lint

Vite Doctor

If your project is a Vite, Vue, Nuxt, or Nitro app, Vite Doctor can run lint-comark for you. It checks the framework mistakes your linter can't see, such as a raw fetch in a Nuxt setup or a secret in Vite's define, and comark-linter/doctor adds every lint-comark rule to the same run:

pnpm add -D comark-linter vite-doctor

// doctor.config.ts
import comark from "comark-linter/doctor";
import { defineDoctorConfig } from "vite-doctor/config";

export default defineDoctorConfig({
  extends: ["auto", "comark/recommended"],
  extensions: [comark({ include: "content/**/*.md" })],
});

{
  "scripts": {
    "lint": "eslint . && vite-doctor . --config doctor.config.ts --max-warnings 0"
  }
}

One report covers the code and the documents, and each lint-comark problem gets its own code, COMARK0001 to COMARK0007, linked to its rule. Most lint-comark rules are warnings, and Vite Doctor exits with 0 on warnings alone, so --max-warnings 0 is what fails the script. In a coding agent's terminal it prints a compact report with the fix for each problem, and --format sarif gives GitHub code scanning a file it can annotate a pull request with. Vite Doctor lists the options.