mdq: jq for Markdown

What is mdq?

mdq aims to do for Markdown what jq does for JSON: provide an easy way to zero in on specific parts of a document.

For example, GitHub PRs are Markdown documents, and some organizations have specific templates with checklists for all reviewers to complete. Enforcing these often requires ugly regexes that are a pain to write and worse to debug. Instead, you can (for example) ask mdq for all uncompleted tasks:

mdq '- [ ]'

mdq is available under the Apache 2.0 or MIT licenses, at your option. I am open to other permissive licenses, if you have one you prefer.

Installation

Any of these will work:

1. cargo install --git https://github.com/yshavit/mdq

2. You can download binaries from the latest release (or any other release, of course).
3. You can also grab the binaries from the latest build-release workflow run. You must be logged into GitHub to do that (their limitation, not mine!)

[!Tip]

• These binaries are all built on GitHub's servers, so if you trust my code (and dependencies), and you trust GitHub, you can trust the binaries.

  See the wiki page on release binaries for information on how to verify them.

• You'll have to chmod +x them before you can run them.

Basic Usage

# Select sections containing "usage":
$ cat example.md | mdq '# usage'

# Select sections containing "usage", and within those find all unordered list items:
$ cat example.md | mdq '# usage | -'

# ... or maybe you only want the list items containing "note":
$ cat example.md | mdq '# usage | - note'

You can select...

• Sections:

  $ cat example.md | mdq '# foo'       # find headers whose title contains "foo"

• Lists and tasks:

  $ cat example.md | mdq '- foo'       # find unordered list items containing "foo"
  $ cat example.md | mdq '1. foo'      # find ordered list items containing "foo"
                                     #   (note: the number must be exactly "1.")
  $ cat example.md | mdq '- [ ] foo'   # find uncompleted task items containing "foo"
  $ cat example.md | mdq '- [x] foo'   # find completed task items containing "foo"
  $ cat example.md | mdq '- [?] foo'   # find all task items containing "foo"

• Links and images:

  $ cat example.md | mdq '[foo](bar)'  # find links with display text containing "foo"
                                     # and URL containing "bar"
  $ cat example.md | mdq '![foo](bar)' # ditto for images

• Block quotes:

  $ cat example.md | mdq '> foo'  # find block quotes containing "foo"

• Code blocks:

  $ cat example.md | mdq '```rust fizz'  # find code blocks for rust with "fizz" within them

• HTML (inline or block):

  $ cat example.md | mdq '</> foo'  # find html tags containing "foo"

• Paragraphs

  $ cat example.md | mdq 'P: foo'  # find paragraphs containing "foo"

• Tables

  $ cat example.md | mdq ':-: "some headers" :-: "some rows"'

  (Tables selection differs from other selections in that you can actually select only certain headers and rows. See the wiki for more.)

The foos and bars above can be:

• an unquoted string that starts with a letter, as shown above
• a "quoted string" (either single or double quotes)
• a string (quoted or unquoted) anchored by ^ or $ (for start and end of string, respectively)
• a /regex/
• omitted, to mean "any"

See the tutorial for a bit more detail, and user manual for the full picture.