Processing Markdown with mq

Quick Reference

Selectors

| Selector | Description | | ---------------- | ---------------------- | | .h | All headings | | .h1–.h6 | Specific heading level | | .text | Text nodes | | .code | Code blocks | | .code_inline | Inline code | | .strong | Bold text | | .emphasis | Italic text | | .delete | Strikethrough | | .link | Links | | .image | Images | | .list | List items | | .blockquote | Block quotes | | .[][] | Table cells | | .html or .<> | HTML nodes | | .footnote | Footnotes | | .math | Math blocks | | .yaml, .toml | Frontmatter |

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

| Flag | Purpose | | ------------------------------ | -------------------------------------------------------------- | | -A, --aggregate | Combine all inputs into single array | | -I, --input-format | Input format: markdown, mdx, html, text, null, raw | | -F, --output-format | Output format: markdown, html, text, json, none | | -U, --update | Update file in place | | -f, --from-file | Load query from .mq file | | -o, --output | Write to output file | | -S, --separator | Insert query result between files | | --args NAME VALUE | Set runtime variable | | --rawfile NAME FILE | Load file into variable | | --stream | Process line by line | | --csv, --yaml, --toml, --xml | Load built-in modules | | -C, --color-output | Colorize output | | -P THRESHOLD | Parallel processing threshold |

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