md2llm

A command-line interface for converting markdown files to LLM rules, built with Commander.js.

Requirements

• Node.js 20 or greater required
• Node.js 22+ recommended (uses latest APIs)

What is md2llm?

md2llm extracts code examples from your markdown documentation and converts them into LLM rules. Unlike sending entire documentation files to LLMs, this tool focuses on the most valuable content: working code examples.

Why Code Examples?

• More Effective Context: Code examples provide concrete, actionable patterns that LLMs can follow
• Token Efficiency: Instead of sending entire docs, you get focused, relevant code snippets
• Better Results: LLMs perform better with specific examples rather than verbose documentation

IDE Compatibility

Your existing markdown files work seamlessly with:

• VSCode - Native markdown support with syntax highlighting
• IntelliJ IDEA - Full markdown editing and preview capabilities
• Other editors - Any editor that supports markdown

Cursor Integration

When using the .mdc format, md2llm automatically adds front matter metadata that Cursor uses to:

• Apply rules contextually with alwaysApply or glob patterns
• Set rule descriptions
• Configure rule behavior for specific file types or directories

IDE-Specific Setups

md2llm generates markdown files that can be referenced by IDE-specific instruction files:

IntelliJ IDEA with Junie

• Location: .junie/guidelines.md
• Usage: Junie reads coding guidelines from this file
• Integration: Link to generated rules from your guidelines file

GitHub Copilot

• Location: .github/copilot-instructions
• Usage: Copilot uses these instructions for project-specific guidance
• Integration: Reference generated rules from your Copilot instruction file

Claude Desktop

• Location: CLAUDE.md (project root)
• Usage: Claude reads project context from this file
• Integration: Link to generated rules from your CLAUDE.md file

Example workflow:

# Generate rules first
md2llm ./rules ./docs --source-url "https://github.com/user/repo/blob/main/"

# Then reference them in your IDE files:
# .junie/guidelines.md:
# See our coding patterns: ./rules/function-patterns.md

# .github/copilot-instructions:
# Follow examples in: ./rules/api-examples.md

# CLAUDE.md:
# Check our guidelines: ./rules/component-patterns.md

Installation

npm install -g md2llm

Local Development Installation

npm i -g .

Usage

Running the CLI

# Convert markdown files to .md rules
md2llm ./output ./docs ./src

# Convert to .mdc format (Cursor rules)
md2llm ./output ./docs --format mdc

# .mdc with custom rule application
md2llm ./output ./docs --format mdc --no-always-apply
md2llm ./output ./docs --format mdc --apply-glob "**/*.{js,ts}"
md2llm ./output ./docs --format mdc --apply-glob "src/components/**/*"

# Custom exclude directories
md2llm ./output ./docs --exclude "temp,backup,old"

# Custom source URL for links
md2llm ./output ./docs --source-url "https://github.com/user/repo/blob/main/"

# Multiple source directories
md2llm ./output ./docs ./src ./examples

Options

• -f, --format <format> - Output format (md or mdc), default: md
• -e, --exclude <dirs> - Comma-separated list of directories to exclude (default: images,node_modules,dist,build,coverage,test,cjs,generator,lib,src)
• -s, --source-url <url> - Base URL for source links

MDC Rule Configuration Options

• --always-apply - Set alwaysApply: true in mdc frontmatter (default for mdc format)
• --no-always-apply - Set alwaysApply: false in mdc frontmatter
• --apply-glob <pattern> - Use glob pattern instead of alwaysApply in mdc frontmatter

Features

• Modular Architecture: Clean, testable, and extensible codebase
• Code Snippet Extraction: Automatically extracts code blocks from markdown
• Multiple Formats: Supports both .md and .mdc (Cursor) output formats
• Configurable MDC Rules: Control when Cursor applies rules via alwaysApply or glob patterns
• Package Integration: Handles package.json scoping for README files
• Smart Filtering: Excludes common non-documentation files (CHANGELOG, LICENSE, etc.)
• Configurable Exclusions: Custom directory exclusion patterns
• Source URL Support: Custom base URLs for source links
• Comprehensive Testing: Full test suite with unit, integration, and CLI tests

Output Format

MD Format

Output file structure:

TITLE: Example Function
DESCRIPTION: A simple JavaScript function
SOURCE: docs/example.md
LANGUAGE: javascript
CODE:
function greet(name) {
  return `Hello, ${name}!`;
}
----------------------------------------
@example

MDC Format (Cursor)

The .mdc format includes frontmatter that configures when Cursor applies the rules:

Default (Always Apply)

---
description: example
alwaysApply: true
---

Conditional Application (--no-always-apply)

---
description: example
alwaysApply: false
---

Glob Pattern Application (--apply-glob)

---
description: example
glob: "**/*.{js,ts}"
---

Complete output file structure:

---
description: example
alwaysApply: true
---

TITLE: Example Function
DESCRIPTION: A simple JavaScript function
SOURCE: docs/example.md
LANGUAGE: javascript
CODE:
function greet(name) {
  return `Hello, ${name}!`;
}
----------------------------------------
@example

MDC Rule Configuration Examples

Apply rules only to React components:

md2llm ./rules ./docs -f mdc --apply-glob "**/*.{jsx,tsx}"

Apply rules only to TypeScript files:

md2llm ./rules ./docs -f mdc --apply-glob "**/*.{ts,tsx}"

Apply rules only to specific directories:

md2llm ./rules ./docs -f mdc --apply-glob "src/components/**/*"

Disable automatic rule application:

md2llm ./rules ./docs -f mdc --no-always-apply

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Architecture

The tool is built with a modular architecture:

• CLI Layer: Command handling and option validation
• Core Layer: Main conversion orchestration
• Processors: Markdown parsing and snippet extraction
• Formatters: Output format generation
• Utilities: File operations and URL management

See src/README.md for detailed architecture documentation.

Testing

The project includes comprehensive tests:

• Unit Tests: Individual module functionality
• Integration Tests: End-to-end conversion process
• CLI Tests: Real CLI execution scenarios

All tests use Node.js built-in test runner and achieve 100% pass rate.