like jq but for Markdown: find specific elements in a md doc
like jq but for Markdown: find specific elements in a md doc
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.
[!tip] You can try mdq live in your browser at https://yshavit.github.io/mdq-playground.
To install mdq locally, any of these will work:
# (Mac and Linux, with brew installed)
brew install mdq
docker pull yshavit/mdq
echo 'My [example](https://github.com/yshavit/mdq) markdown' | docker run --rm -i yshavit/mdq '[]()'
To use a specific release version, use yshavit/mdq:<version>. See Docker Hub for available version tags.
Download binaries from the latest release (or any other release, of course).
Mac usersMacs quarantine downloads from the internet by default. If you get an error saying that Apple cannot check the binary for malicious software, you can remove this flag by running the following on the binary after extracting it from the artifact zip:
xattr -d com.apple.quarantine mdq
The release and latest-workflow binaries are built on GitHub's servers, so if you trust my code (and dependencies), and you trust GitHub, you can trust the binaries. See https://github.com/yshavit/mdq/wiki/Release-binaries for information on how to verify them.
Non-release buildsYou can also grab the binaries from the latest build-release workflow run. You must be logged into GitHub to do
that (this is GitHub's limitation, not mine). You'll have to chmod +x them before you can run them.
cargo install --git https://github.com/yshavit/mdq
Requires rustc >= 1.85.1
Simple example to select sections containing "usage":
cat example.md | mdq '# usage'
Use pipe (|) to chain filters together. For example, to select sections containing "usage", and within those find
all unordered list items:
cat example.md | mdq '# usage | -'
The filter syntax is designed to mirror Markdown syntax. You can select...
| Element | Syntax |
|---|---|
| Sections | # title text |
| Lists | - unordered list item text |
| " | 1. ordered list item text |
| " | - [ ] uncompleted task |
| " | - [x] completed task |
| " | - [?] any task |
| Links | [display text](url) |
| Images | `` |
| Block quotes | > block quote text |
| Code blocks | ` |
…
bash if echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' ; then ...
(The `-q` option is like grep's: it doesn't output anything to stdout, but exits 0 if any items were found, or non-0 otherwise.)
This will match:
> - [x] I have searched for existing issues
... but will fail if the checkbox is unchecked:
> - [ ] I have searched for existing issues
### Extracting a referenced ticket
Some organizations use GitHub Actions to update their ticket tracker, if a PR mentions a ticket. You can use mdq to extract the link from Markdown as JSON, and then use jq to get the URL:
```bash
TICKET_URL="$(echo "$PR_TEXT"
| mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)'
| jq -r '.items[].link.url')"
This will match Markdown like:
Ticket
Let's say you have a table whose columns reference people in an on-call schedule, rows correspond to weeks in YYYY-MM-DD format:
On-Call Alice Bob Sam Pat 2024-01-08 x 2024-01-15 x 2024-01-22 x
To find out when Alice is on call:
cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
| On-Call | Alice |
|:----------:|:-----:|
| 2024-01-08 | x |
| 2024-01-15 | |
| 2024-01-22 | |
Or, to find out who's on call for the week of Jan 15:
cat oncall.md | mdq ':-: * :-: 2024-01-15'
| On-Call | Alice | Bob | Sam | Pat |
|:----------:|:-----:|:---:|:---:|----:|
| 2024-01-15 | | | x | |
mdq is available as a Rust library at https://crates.io/crates/mdq. Its docs are available at https://docs.rs/mdq/latest/mdq/.
Requires rustc >= 1.85.1
cargo build
cargo test
No open issues yet, or sync has not completed.