contextlint

npm version cli downloads mcp-server downloads lsp-server downloads CI License: Apache 2.0

🌐 ζ—₯本θͺž | δΈ­ζ–‡ | ν•œκ΅­μ–΄

A rule-based linter for structured Markdown documents. Catch broken references, duplicate IDs, missing sections, and structural issues β€” deterministically, in seconds, CI-friendly.

πŸ“š Full reference and guides: https://contextlint.dev

Why contextlint?

In AI-driven workflows like SDD (Spec Driven Development), Markdown documents form a dependency graph: requirements reference IDs, design docs link back to specs, ADRs cross-reference each other. When that graph silently breaks β€” a deleted requirement, a mistyped ID, a missing section β€” the consequence shows up only at read time.

contextlint provides deterministic, static validation for structured Markdown. No AI, no cost, CI-friendly.

contextlint focuses on content semantics and cross-file integrity. For Markdown syntax, formatting, and style, use markdownlint alongside contextlint β€” they complement each other well.

Quick Start

AI-assisted (recommended) β€” for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and any Agent Skills-compatible client. Requires GitHub CLI v2.90+:

gh skill install nozomi-koborinai/contextlint contextlint-init

Then ask your agent to "set up contextlint". The skill detects your repo layout, infers rules, installs the CLI, and writes contextlint.config.json for you.

Manual setup:

npm install -D @contextlint/cli
npx contextlint init
npx contextlint

Sample output:

docs/requirements.md
  line 3   warning  Empty cell in column "Status"  TBL-002

docs/design.md
  line 12  error    Link target "./api.md" does not exist  REF-001

1 error, 1 warning in 2 files

Rules

contextlint ships 21 rules across 7 categories:

Prefix Category What it validates Count
TBL Table Required columns, empty cells, allowed values, patterns, cross-column constraints, cross-file ID uniqueness 6
SEC Section Existence and order of section headings 2
STR Structure Project-level file existence 1
REF Reference Links, anchors, cross-file ID references, stability consistency, zone dependencies, image references 6
CHK Checklist Checklist completion status 1
CTX Context Placeholder detection, term consistency 2
GRP Graph Traceability chains, circular references, orphan documents 3

See Rules for the full per-rule reference.

Learn more

For commands beyond lint (init, impact, slice, graph, compile, --watch), run npx contextlint --help or browse the docs:

Topic Link
Get Started https://contextlint.dev/docs/get-started/
Configuration reference https://contextlint.dev/docs/configuration/
Rule reference (all 21) https://contextlint.dev/docs/rules/
CLI commands and flags https://contextlint.dev/docs/integrations/cli/
Editor integration (LSP) https://contextlint.dev/docs/integrations/editors/
AI agents (MCP, Agent Skills) https://contextlint.dev/docs/integrations/ai-agents/
CI/CD integration https://contextlint.dev/docs/integrations/ci-cd/
Recipes (ADR / SDD / monorepo) https://contextlint.dev/docs/recipes/
Programmatic Graph API https://contextlint.dev/docs/graph-api/

Packages

Package Description
@contextlint/core Rule engine and Markdown parser
@contextlint/cli CLI entry point (contextlint command)
@contextlint/mcp-server MCP server for AI tool integration
@contextlint/lsp-server Language Server Protocol implementation
contextlint-vscode VS Code / Cursor extension β€” install the VSIX from GitHub Releases until Marketplace publishing lands

Resources

License

Apache 2.0