mq

A jq-like command-line tool for querying and transforming Markdown files

TLDR

Extract all headings from a Markdown file

$ mq '.h' [path/to/file.md]

Select a specific section by heading text

$ mq 'select("Section Name")' [path/to/file.md]

Extract code blocks of a specific language

$ mq '.code("python")' [path/to/file.md]

Convert Markdown to plain text

$ mq 'to_text' [path/to/file.md]

Output as HTML

$ mq -F html '.h1' [path/to/file.md]

Launch interactive REPL mode

$ mq repl [path/to/file.md]

Load query from a file

$ mq -f [query.mq] [path/to/file.md]

Aggregate multiple files into a single array

$ mq -A '.h1' [*.md]

SYNOPSIS

mq [options] [query] [files...]mq repl [file]mq fmt [options] [file]

mq is a command-line tool for processing and querying Markdown files, inspired by jq for JSON. It lets you slice, filter, map, and transform structured Markdown content directly from the terminal with built-in selectors (`.h1`-`.h6`, `.code`, `.link`, `.image`, `..` for recursive descent), functions (`select()`, `contains()`, `totext()`, `tolink()`), and support for custom extensions.Useful for preparing structured prompts for language models, automating documentation updates, and analyzing content across multiple Markdown files. Extensible via custom subcommands placed in `~/.mq/bin/`.

PARAMETERS

-A, --aggregate

Combine all input files into a single array for processing.

-f file, --from-file file

Load the query filter from a file instead of a command-line argument.

-I format, --input-format format

Set input format: markdown, mdx, html, text, null, or raw.

-F format, --output-format format

Set output format: markdown, html, text, json, or none.

-U, --update

Update input files in-place with the query result.

-o file, --output file

Write output to the specified file.

-C, --color-output

Colorize Markdown output.

-S query, --separator query

Query to insert between files when processing multiple inputs.

-L dir, --directory dir

Search path for modules.

-M modules, --module-names modules

Load specific modules (json, csv, yaml, toml, xml).

CAVEATS

Queries follow mq's own filter syntax similar to jq. Complex transformations may require chaining multiple filters with the pipe (`|`) operator.

HISTORY

mq was created by harehare and is written in Rust.

mq