mq: Markdown Query and Extraction Tool

Use mq to extract specific elements from Markdown files without loading entire file contents into context.

When to Use mq vs Read

Use mq when:

• Need specific element(s) from Markdown file (headers, code blocks, links, tables)
• File is large (>50 lines) and only need subset
• Querying document structure
• Extracting code samples, URLs, or table data
• Saves 80-95% context vs reading entire file

Just use Read when:

• File is small (<50 lines)
• Need to understand overall structure
• Making edits (need full context anyway)

Common File Types

Markdown files where mq excels:

• README.md, CHANGELOG.md, documentation
• GitHub wiki pages
• Technical specifications
• API documentation with code samples

Quick Examples

# Get all code blocks
mq '.code' README.md

# Get code blocks by language
mq '.code("rust")' file.md

# Get all links (URLs only)
mq '.link.url' file.md

# Get all headers
mq '.h' README.md

# Get level-2 headers only
mq '.h2' file.md

# Extract table data
mq '.[][]' file.md

# Extract YAML frontmatter (raw)
mq '.yaml.value' file.md

# Parse frontmatter to JSON (pipe to yq)
mq '.yaml.value' file.md | yq -o json

Core Principle

Extract exactly what is needed in one command - massive context savings compared to reading entire Markdown files.

Detailed Reference

For comprehensive mq patterns, syntax, and examples, load mq guide:

• Core patterns (80% of use cases)
• Element selectors (code, links, headers, tables, lists)
• Filtering and transformation
• Output formats
• Integration with other tools