Mdq
title: mdq radar_quadrant: Tools radar_ring: Assess radar_position: inner created: 2026-05-26 last_updated: 2026-05-26 tags: [markdown, cli, scripting, documentation, jq] source_url: https://github.com/yshavit/mdq
A command-line tool for querying and extracting structured elements from Markdown files, analogous to how jq queries JSON. Given a Markdown document, mdq can select specific headings and their content, code blocks, links, tables, or list items using a concise query syntax.
mdq accepts a selector expression and reads Markdown from stdin or a file. Selectors target Markdown structural elements:
-
# Heading text— selects a heading and its content block -
```— selects all fenced code blocks -
[link]— selects all hyperlinks -
- list item— selects list items matching a pattern
Output is Markdown, making it composable with other Markdown-aware tools or further mdq queries.
The primary use case is scripting against Markdown-heavy repositories or documentation systems. Examples include extracting all code blocks from a runbook for validation, pulling all links from a wiki page for link-checking, or isolating a specific section for further processing without loading an entire document into an LLM context.
In a wiki or documentation pipeline, mdq fills the gap between grep (text-only, structure-unaware) and a full Markdown parser (heavyweight, requires code).
Placed in Tools / Assess / inner. Fills a genuine gap for Markdown-as-data workflows. Inner position reflects zero infrastructure cost (single binary), direct applicability to this wiki's scripting context, and composability with existing CLI tooling (jq, jc, just). Trial gate: one scripting task against a real Markdown corpus where mdq replaces a grep or manual parse — for example, extracting all links or code blocks from wiki articles for automated validation.
