Processing Markdown with mq

Quick Reference

Selectors

Attribute Access

.h.level           # Heading level (1-6)
.h.depth           # Same as .h.level
.code.lang         # Code block language
.code.value        # Code block content
.link.url          # Link URL
.link.title        # Link title
.image.url         # Image URL
.image.alt         # Image alt text
.list.index        # List item index
.list.level        # Nesting level
.list.ordered      # Whether ordered list
.list.checked      # Checkbox state
.[0][0].row        # Table cell row
.[0][0].column     # Table cell column

Common Patterns

Extract Elements

mq '.h' file.md                         # All headings
mq '.h1' file.md                        # Only h1 headings
mq '.code' file.md                      # All code blocks
mq '.link.url' file.md                  # All URLs
mq '.image.alt' file.md                 # All image alt texts

Filter with select

mq 'select(.code)' file.md              # Only code blocks
mq 'select(!.code)' file.md             # Everything except code blocks
mq 'select(.h.level <= 2)' file.md      # h1 and h2 only
mq 'select(.code.lang == "rust")' file.md  # Rust code blocks only
mq 'select(contains("TODO"))' file.md   # Nodes containing "TODO"

Transform Content

mq '.h | to_text()' file.md             # Headings as plain text
mq '.code | to_text()' file.md          # Code block content as text
mq '.link | to_string()' file.md        # Links as strings

Generate Table of Contents

.h
| let link = to_link("#" + to_text(self), to_text(self), "")
| let level = .h.depth
| if (!is_none(level)): to_md_list(link, level - 1)

Multi-File Processing

mq -A 'pluck(.code.value)' *.md         # Collect all code values
mq -S 's"\n---\n"' 'identity()' *.md    # Merge files with separator

Important: HTML Input and Selectors

When using -I html, mq first converts HTML to Markdown, then queries the resulting Markdown AST. You must always use Markdown selectors, not HTML element names.

# WRONG: HTML element selectors do NOT work
curl -s https://example.com | mq -I html '.p | to_text()'        # Error: Unknown selector `.p`
curl -s https://example.com | mq -I html '.a | to_text()'        # Error: Unknown selector `.a`
curl -s https://example.com | mq -I html '.div | to_text()'      # Error: Unknown selector `.div`

# CORRECT: Use Markdown selectors regardless of input format
curl -s https://example.com | mq -I html '.text | to_text()'     # Extract text nodes
curl -s https://example.com | mq -I html '.link | to_text()'     # Extract links (HTML <a> → .link)
curl -s https://example.com | mq -I html '.h | to_text()'        # Extract headings (HTML <h1>-<h6> → .h)
curl -s https://example.com | mq -I html '.code | to_text()'     # Extract code blocks (HTML <pre><code> → .code)
curl -s https://example.com | mq -I html '.image'                # Extract images (HTML <img> → .image)
curl -s https://example.com | mq -I html '.strong'               # Extract bold text (HTML <strong>/<b> → .strong)
curl -s https://example.com | mq -I html '.emphasis'             # Extract italic text (HTML <em>/<i> → .emphasis)
curl -s https://example.com | mq -I html '.list'                 # Extract list items (HTML <ul>/<ol>/<li> → .list)
curl -s https://example.com | mq -I html '.blockquote'           # Extract blockquotes (HTML <blockquote> → .blockquote)

The -I html flag only changes the input parser — the query language and selectors remain the same as for Markdown input.

CLI Options

For complete function reference, see REFERENCE.md. For advanced patterns and examples, see EXAMPLES.md.

When NOT to Use mq

• Binary file processing
• Non-Markdown structured data (use jq for JSON, yq for YAML instead)
• Simple cat or echo operations where no transformation is needed