Basic usage: mdq [OPTIONS] [SELECTORS] [FILE...] Reads stdin if no file is given. Multiple files are concatenated.
<string_matching> Case-insensitive, must start with a letter. Example: installation Case-sensitive with escape sequences. Example: "Getting Started" /pattern/ using fancy-regex. Example: /getting.started/i * or empty matches anything. ^start or end$ for position anchoring. </string_matching>
# Get code blocks from the "Examples" section
mdq '# examples | ```' guide.md
# Find checked tasks in the "Release" section
mdq '# release | - [x]' CHANGELOG.md
<output_options>
<decision_tree name="when_to_use_mdq"> Do you need to extract or query specific elements from a Markdown file? Use # selector, optionally chain with child selectors Use - [ ] / - [x] / - [?] selectors; use -q for scripting Use selector with --output json for structured data Use ``` selector with optional language filter Use standard text tools (grep, awk) or a Markdown parser library </decision_tree>
<best_practices> Chain selectors with | to narrow scope before extracting child elements Use --quiet (-q) and exit codes in CI/CD scripts instead of parsing stdout output Use --output json when piping results to jq or other structured-data tools Use regex selectors /pattern/i for case-insensitive matching in cross-platform environments Prefer --output plain for text processing pipelines that do not need Markdown formatting </best_practices>
<anti_patterns> Applying mdq to non-CommonMark formats (AsciiDoc, RST, HTML) expecting Markdown-like results Use mdq only on CommonMark Markdown files; use format-specific tools for other document types
<error_escalation inherits="core-patterns#error_escalation"> No matches found (exit code 1 in --quiet mode) Unexpected output format or extra content extracted Wrong content extracted; selector matches unintended elements mdq binary not found or not installed </error_escalation>
<related_agents> Locate Markdown files in the codebase before querying them Use extracted content to generate or update documentation </related_agents>
<related_skills> General documentation authoring and structure Finding and querying files in a codebase </related_skills>