processing-markdown

Processing Markdown with mq

Core 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 / .<>	HTML nodes
.footnote	Footnotes
.math	Math blocks
.yaml, .toml	Frontmatter
.link_ref	Link references
.image_ref	Image references
.definition	Link/image definitions

Selector Calls (Filtered Matching)

.h(1)          # Only h1 headings
.h(2, 3)       # h2 and h3 headings
.h(1..3)       # h1 through h3 (range)
.code("rust")  # Only Rust code blocks

Key Attribute Access

.h.level / .h.depth   # Heading level (1–6)
.h.value              # Heading text
.code.lang            # Code language
.code.value           # Code content
.link.url             # Link URL
.image.alt            # Image alt text
.list.checked         # Checkbox state (boolean)
."key"                # Dict key access (property selector)

Update Operator

.code.lang |= "rust"           # Change code language in-place
.link.url  |= "https://new"    # Update link URL

Recursive Descent

..ident    # Recursively select matching nodes in nested structures

Common Patterns

# Extract
mq '.h' file.md                              # All headings
mq '.h(2)' file.md                           # h2 only
mq '.code("rust")' file.md                  # Rust code blocks
mq '.link.url' file.md                       # All URLs
mq '.yaml | to_text' post.md              # Frontmatter

# Filter
mq 'select(.code)' file.md                  # Only code blocks
mq 'select(!.code)' file.md                 # Exclude code blocks
mq 'select(.h.level <= 2)' file.md          # h1 and h2 only
mq 'select(contains("TODO"))' file.md       # Nodes with "TODO"

# Transform
mq '.h | to_text' file.md                 # Headings as plain text
mq -U '.code.lang |= "rust"' file.md        # Update in place

# Multi-file
mq -A 'pluck(.code.value)' *.md             # Collect code values, per file
mq --eval-all -A '.h | to_text' *.md        # Combine all files into one query (e.g. cross-file TOC)
mq -S 's"\n---\n"' 'identity' *.md       # Merge with separator

# mq accepts multiple file args directly (shell glob expansion) —
# no need to loop over files in bash:
mq '.h | to_text' *.md work/*.md docs/*.md

# Format conversion
mq -F html 'identity' file.md             # Markdown → HTML
mq -F json '.h | to_text' file.md         # Headings → JSON
mq -I html 'identity' page.html           # HTML → Markdown

# Streaming large files
mq --stream 'select(contains("ERROR"))' large.md

# Section operations (needs -A or `nodes` — see EXAMPLES.md)
mq -A 'section::section("Installation")' file.md                                                             # Extract section by heading
mq -A 'section::filter_sections(fn(s): section::title(s) != "Deprecated";) | section::collect()' file.md    # Delete section by heading