mdq

https://github.com/yshavit/mdq
Admin
mdq is a command-line tool that allows users to query and extract specific parts of Markdown...
Tokens:8,720
Snippets:92
Trust Score:8.8
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install mdq via Cargo

Source: https://github.com/yshavit/mdq/blob/main/README.md

Installs the `mdq` tool directly from its Git repository using Cargo, Rust's package manager. This method requires a Rust development environment with `rustc` version 1.78.0 or newer installed.

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

--------------------------------

### Install mdq via Homebrew

Source: https://github.com/yshavit/mdq/blob/main/README.md

Installs the `mdq` command-line tool on macOS and Linux systems using the Homebrew package manager. This is a convenient method for users with Homebrew already set up.

```shell
brew install mdq
```

--------------------------------

### Code Block with 'types' Language

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

A simple code block demonstrating the 'types' language, showing multi-line content.

```types
here is some code
it is

fun
```

--------------------------------

### mdq Piping Syntax Example

Source: https://github.com/yshavit/mdq/wiki/Home

Demonstrates the piping syntax in mdq selectors, where '|' is used to chain operations. This example shows how to select elements within a header and then filter for lists containing links.

```text
'# within some header | - look for lists | [with links]()'
```

--------------------------------

### Code block with metadata

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

A text code block demonstrating the use of metadata in markdown, specifically a 'title' attribute.

```text
Block A
```

--------------------------------

### Code block with only metadata

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

A generic code block demonstrating the use of a 'title' metadata attribute without an explicit language identifier.

```plaintext
Block B
```

--------------------------------

### MDQ Regular Expression Matching Examples

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Examples of regular expressions used in MDQ, demonstrating basic patterns, start (`^`) and end (`$`) anchors, and case-insensitive matching using the `(?i)` flag. MDQ uses the `regex` crate syntax.

```text
/hello.+world/
```

```text
/^hello/
```

```text
/world$/
```

```text
/(?i)HELLO/
```

--------------------------------

### Generic Code Block within List Item (1)

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

An untyped code block embedded within a list item, showing basic multi-line content.

```plaintext
foo
bar
```

--------------------------------

### Example mdq Selector Usage

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Demonstrates a practical application of mdq selectors using a bash command to filter Markdown content based on section and list item criteria.

```bash
$ cat example.md | mdq '# usage | -'
```

--------------------------------

### Generic Code Block after List Item

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

An untyped code block appearing directly after a list item, showcasing a simple code snippet.

```plaintext
foo
```

--------------------------------

### Run mdq using Docker

Source: https://github.com/yshavit/mdq/blob/main/README.md

Illustrates how to pull the `mdq` Docker image and execute `mdq` against a Markdown string provided via standard input. This method allows users to run `mdq` without a local installation, ensuring environment consistency.

```bash
docker pull yshavit/mdq
echo 'My [example](https://github.com/yshavit/mdq) markdown' | docker run --rm -i yshavit/mdq '[]()'
```

--------------------------------

### Generic Code Block within List Item (2)

Source: https://github.com/yshavit/mdq/blob/main/examples/hello.md

Another untyped code block embedded within a list item, demonstrating a single line of code.

```plaintext
foo
```

--------------------------------

### Sample Markdown Table for MDQ Examples

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

A complete Markdown table with two columns ('Name', 'Description') and three data rows. This table serves as the base data for demonstrating various `mdq` table selection operations and their expected outputs.

```markdown
| Name | Description |
|------|-------------|
| Foo  | the fuzz    |
| Bar  | the buzz    |
| Foot | the unit    |
```

--------------------------------

### mdq Selectors for Markdown Lists and Tasks

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Provides examples of `mdq` selectors for various types of Markdown list items, including unordered lists (`-`), ordered lists (`1.`), and task list items (uncompleted `-[ ]`, completed `-[x]`, or any `-[?]`).

```bash
$ 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"
```

--------------------------------

### Markdown Table for Syntax Explanation

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

A simple Markdown table example used to visually explain the conceptual progression that led to the `mdq` table selector syntax. It features a single header and data row with center alignment.

```markdown
| my header |
|:---------:|  // 🡐 :-: is center-alignment
| data row  |
```

--------------------------------

### MDQ Quoted String Matching Examples

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Examples illustrating the use of single and double-quoted strings in MDQ, including how to embed quotes, the effect of escape sequences like `\n` for newlines, and the correct syntax for Unicode escapes (`\u{...}`).

```text
"hello's world"
```

```text
'my "hello world" message'
```

```text
'my \"hello world\" message'
```

```text
"A string with\nTwo lines"
```

```text
"I love \u{2603} in the winter"
```

```text
"I love \u2603 in the winter"
```

--------------------------------

### mdq Selectors for List Items

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet provides mdq selector examples for both unordered and ordered list items in markdown. It distinguishes between the syntax for bullet points and numbered lists.

```text
- unordered list item
1. ordered list item
```

--------------------------------

### MDQ Quoted String Shell Command Example

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

An example demonstrating how to use an escaped backtick (`\` ```) within a double-quoted shell command to represent a single quote, facilitating easier integration with shell environments like bash or zsh.

```text
mdq '# don\`t speak'
```

--------------------------------

### mdq Selectors for Markdown Task Lists

Source: https://github.com/yshavit/mdq/wiki/Home

This example demonstrates mdq selectors for various states of task list items, including uncompleted, completed, and any task. It highlights the specific syntax for matching checkbox states.

```text
- [ ] uncompleted task
- [x] completed task
- [?] any task
```

--------------------------------

### mdq Selectors for Markdown Links and Images

Source: https://github.com/yshavit/mdq/wiki/Home

This example shows mdq selectors for matching markdown links and images. The first line targets a standard hyperlink, while the second targets an image with alt text, demonstrating different markdown element selections.

```text
[link text](url)
![img alt](url)
```

--------------------------------

### mdq Selector for Paragraph Text

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet demonstrates the mdq selector syntax for matching paragraph text. It provides a straightforward example of how to target standard text blocks.

```text
P: paragraph text
```

--------------------------------

### mdq JSON Output for Image Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Explains that image JSON structure is similar to links, but uses 'image' as type and 'alt' for display text. This example combines all possible fields.

```json
{
  "image": {
    "alt": "Markdown text. Inline elements like _emphasis_ are rendered as Markdown",
    "url": "https://example.com",
    "title": "image title",
    "reference": "1",
    "reference_style": "collapsed"
  }
}
```

--------------------------------

### MDQ Unquoted String Matching Examples

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Examples demonstrating unquoted string behavior in MDQ, including context-specific ending delimiters, whitespace trimming, and literal character matching. Unquoted strings are case-insensitive and match any substring by default.

```text
# some header text | -
```

```text
[foo]( example.com )
```

```text
# hello, \u{2603}
```

```text
# hello, ☃
```

```text
# fizz # buzz
```

```text
# fizz$
```

--------------------------------

### mdq Selector for Section Titles

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet illustrates the mdq selector syntax for matching a section title in markdown. It provides a direct example of how to target a heading element.

```text
# section title
```

--------------------------------

### Chain mdq filters to select nested elements

Source: https://github.com/yshavit/mdq/blob/main/README.md

Shows how to combine `mdq` filters using the pipe (`|`) operator. This example first selects sections containing 'usage' and then further filters to find all unordered list items within those sections, demonstrating powerful content navigation.

```shell
cat example.md | mdq '# usage | -'
```

--------------------------------

### mdq String Anchoring Syntax

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet shows how to use '^' and '$' characters to anchor string matches to the start, end, or both ends of a string in mdq selectors. This allows for precise control over where a match must occur within the target text.

```text
^☚can anchor to the start of a string...
or to the end... ☛$
^☚ or to both, for full string matching ☛$
```

--------------------------------

### mdq Selector for Block Quotes

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet shows the mdq selector syntax for matching block quotes in markdown. It provides a simple, direct example of how to target quoted text.

```text
> block quotes
```

--------------------------------

### mdq Special String Escape Sequences

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet provides examples of special string escape sequences in mdq. Specifically, it shows how to represent unicode code points ('\u{...}') and how to escape a backtick to produce a single quote, which is a non-standard but documented feature.

```text
\u{2603} ⮕ ☃
\`       ⮕ '
```

--------------------------------

### mdq Unquoted String Matching

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet explains the behavior of unquoted string matching in mdq. It notes that matches are case-insensitive, trim whitespace, and match any substring, provided the unquoted text starts with a letter.

```text
unquoted text when unambiguous (must start with a letter)
matches any substring; prefix and trailing whitespace is trimmed
cAsE iNsEnSiTiVe
```

--------------------------------

### Filter Markdown table to show on-call schedule for a specific date with mdq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Demonstrates using `mdq` to filter an on-call Markdown table to show who is on call for a specific week (January 15th in this example). The command outputs a new Markdown table containing only the row for the specified date.

```bash
cat oncall.md | mdq ':-: * :-: 2024-01-15'
```

--------------------------------

### Basic mdq Usage for Markdown Selection and Chaining

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Demonstrates fundamental `mdq` commands to select specific sections and list items from a Markdown file based on content. Shows how to chain selectors using the `|` character to refine queries.

```shell
# 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'
```

--------------------------------

### Verify MDQ Binary Authenticity with GitHub Attestation

Source: https://github.com/yshavit/mdq/wiki/Release-binaries

Use the `gh` CLI tool (version 2.49.0 or higher) to verify that the `mdq` binary was built by GitHub under the `yshavit` owner. This command leverages GitHub's artifact attestations to confirm the binary's origin and integrity. Remember to specify `-o yshavit` literally and use `mdq.exe` for Windows binaries, or verify both `mdq-installer.sh` and the generated `mdq` for macOS.

```Bash
gh attestation verify -o yshavit mdq
```

--------------------------------

### mdq Selector Syntax Reference

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Comprehensive reference for mdq selector types, their syntax, and what they select, including how string matchers are applied.

```APIDOC
Syntax: # matcher
Selects: section
String matcher matches: section's header title.

Syntax: - matcher
Selects: unordered list items
String matcher matches: text in the list item

Syntax: - [?] matcher
Selects: unordered task items
String matcher matches: text in the list item

Syntax: 1. matcher
Selects: ordered list items
String matcher matches: text in the list item

Syntax: 1. [?] matcher
Selects: ordered task items
String matcher matches: text in the list item

Syntax: [matcher](matcher)
Selects: links
String matcher matches:
  - first matches the link text
  - second matches the URL

Syntax: ![matcher](matcher)
Selects: images
String matcher matches:
  - first matches the image alt text
  - second matches the URL

Syntax: > matcher
Selects: block quotes
String matcher matches: block quote contents

Syntax: ```matcher matcher ```
Selects: code blocks
String matcher matches:
  - first matches the language
  - second matches the code itself

Syntax: </> matcher
Selects: html tags
String matcher matches: html tag contents, including opening and closing angle brackets (< and >)

Syntax: P: matcher
Selects: paragraph
String matcher matches: paragraph text

Syntax: :-: matcher :-: matcher
Selects: tables
String matcher matches:
  - first matches the columns by header
  - second matches rows
```

--------------------------------

### Run mdq project tests with Cargo

Source: https://github.com/yshavit/mdq/blob/main/README.md

Command to execute the test suite for the `mdq` project using Rust's build tool, Cargo. This ensures the project's functionality and stability, and requires Rustc version 1.78.0 or newer.

```bash
cargo test
```

--------------------------------

### mdq Selectors for Markdown Links and Images

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Demonstrates how to use `mdq` to find Markdown links and images based on their display text and URL content. Links are selected using `[text](url)` and images using `![text](url)`.

```bash
$ 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
```

--------------------------------

### mdq Selectors for Matching Any Element

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Explains how to use empty string matchers (`#`) or the `*` wildcard (`# *`) in `mdq` selectors to find all elements of a specific type, regardless of their content. Both methods are equivalent.

```shell
# Find all headers, regardless of their titles:
$ cat example.md | mdq '#'   # an empty selector means "any"
$ cat example.md | mdq '# *' # so does *; they're exactly equivalent
```

--------------------------------

### Build mdq project with Cargo

Source: https://github.com/yshavit/mdq/blob/main/README.md

Command to compile the `mdq` project using Rust's build tool, Cargo. This operation requires Rustc version 1.78.0 or newer to ensure compatibility and successful compilation.

```bash
cargo build
```

--------------------------------

### mdq Query Syntax Reference

Source: https://github.com/yshavit/mdq/blob/main/README.md

A comprehensive reference detailing the `mdq` query syntax for selecting various Markdown elements and the available text matching options. This defines the 'API' for interacting with Markdown content using `mdq` filters.

```APIDOC
mdq Query Language Elements:
- Sections: # title text
- Lists: - unordered list item text
- Lists: 1. ordered list item text
- Lists: - [ ] uncompleted task
- Lists: - [x] completed task
- Lists: - [?] any task
- Links: [display text](url)
- Images: ![alt text](url)
- Block quotes: > block quote text
- Code blocks: ```language <code block text>
- Raw HTML: </> html_tag
- Plain paragraphs: P: paragraph text
- Tables: :-: header text :-: row text
- Front matter: +++[toml|yaml] front matter text

Text Matching Options:
- Unquoted string: case-insensitive, starts with a letter (e.g., 'usage')
- "Quoted string": case-sensitive (single or double quotes, e.g., "my text")
- Anchored string: ^ (start of string) or $ (end of string) (e.g., '^start')
- /Regex/: regular expression (e.g., '/[A-Z]+-\d+$/')
- Omitted or *: matches "any"
```

--------------------------------

### TOML Configuration for Integration Test Cases

Source: https://github.com/yshavit/mdq/blob/main/tests/README.md

Defines the structure of a TOML file used to specify integration test cases. Each file contains a `given` section for input markdown and one or more `expect` sections for expected CLI arguments and output.

```toml
[given]
md = '''
Some input markdown
'''

[expect."test case name"]
cli_args = ["arguments", "passed", "to", "cli"]
output = '''
The expected output
'''

[expect."another text case"]
# ...
```

--------------------------------

### Counting Uncompleted Tasks with mdq JSON Output and jq

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Illustrates how to use `mdq` to output Markdown elements as JSON (`-o json`), pipe the output to `jq` for further processing (e.g., counting uncompleted tasks), and use the result in a shell script for conditional logic.

```shell
# count uncompleted tasks
$ incomplete_tasks="$(cat example.md | mdq -o json '- [ ]' | jq '.items | length')"
$ if [[ "$incomplete_tasks" -gt 0 ]]; then echo 'some tasks are incomplete!'; fi
```

--------------------------------

### mdq Selectors with String Anchors

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Explains how to use `^` and `$` anchors in `mdq` selectors to match strings at the beginning (`^`), end (`$`), or exact full content (`^...$`) of an element. Applicable to both unquoted and quoted strings.

```shell
$ cat example.md | mdq '# ^match start of string'   # unquoted
$ cat example.md | mdq '# ^"match start of string"' # quoted

$ cat example.md | mdq '# match end of string $'    # whitespace trimmed

$ cat example.md | mdq '# ^ match full string $ '
```

--------------------------------

### Query Markdown for sections and lists

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Demonstrates how to use `mdq` to find sections containing 'foo' in their title and then select all unordered lists within those sections. The pipe `|` is used to chain selectors, and quoting is essential for selectors containing special characters like `|`.

```Shell
$ cat example.md | mdq '# foo | - *'
```

--------------------------------

### mdq Selector with Regular Expression Matching

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Shows how to use regular expressions within `mdq` selectors for advanced pattern matching against element content. Regular expressions are enclosed in forward slashes (`/`).

```shell
$ cat example.md | mdq '# /reg(ex|ular expressions)/'
```

--------------------------------

### mdq JSON Output for Collapsed or Shortcut Link

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Outlines the JSON structure for Markdown collapsed or shortcut links, including display text, URL, optional title, and the reference style.

```markdown
[collapsed _markdown_][]

[collapsed _markdown_]: https://example.com "link title"
```

```json
{
  "display": "collapsed _markdown_",
  "url": "https://example.com",
  "title": "'link title' (omitted if absent)",
  "reference_style": "collapsed"
}
```

--------------------------------

### mdq Regular Expression Matching

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet demonstrates the use of regular expressions for string matching in mdq selectors. It shows how to define a regex pattern and how anchoring works within these patterns for advanced matching.

```text
/reg(ex|ular expressions)/
/^ *\(also match substring, unless anchored\)$/
```

--------------------------------

### mdq Selectors for Links and Images

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Describes the syntax for mdq selectors used to match links and images in Markdown. It covers matching link text/alt text and URLs, and notes the normalization of Markdown links on output. The URL matcher works identically on all link forms.

```mdq
[matcher]
![matcher]
```

```markdown
- [as a reference][1]
- [inline](https://example.com)
- [collapsed][]  (GitHub extension)
- [shortcut]     (GitHub extension)

[1]: https://example.com/1

[collapsed]: https://example.com/collapsed

[shortcut]: https://example.com/shortcut
```

```mdq
[]()
```

```mdq
[hello]()
```

```mdq
![](^https://example.com/)
```

--------------------------------

### mdq List and Task Selector Syntax

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Syntax for selecting unordered and ordered list items, including task items. Explains required spacing and specific numbering for ordered lists.

```mdq-syntax
- unordered list
- [?] unordered task
1. ordered list
1. [?] ordered task
```

--------------------------------

### mdq JSON Output for Reference Link

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Details the JSON structure for a Markdown reference-style link, including its display text and the reference identifier.

```markdown
[Markdown text. Inline elements like _emphasis_ are rendered as Markdown][1]
```

```json
{
  "display": "Markdown text. Inline elements like _emphasis_ are rendered as Markdown",
  "reference": "1"
}
```

--------------------------------

### mdq Selector for Markdown Tables

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet illustrates the mdq selector syntax for matching table headers and rows in markdown. It shows the specific syntax used to identify tabular data structures.

```text
:-: table headers :-: table rows
```

--------------------------------

### MDQ Table Selector Base Syntax

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Illustrates the fundamental `mdq` syntax for table selection, specifying placeholders for column and row matchers. The `columns` matcher is mandatory, while the `rows` matcher can be empty to imply all rows.

```mdq
:-: columns :-: rows
```

--------------------------------

### mdq String Matcher Types

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Details on the various types of string matchers supported by mdq selectors, including bareword, quoted, regex, and 'any' matchers.

```APIDOC
String matchers can be:
- bareword strings (case insensitive)
- quoted strings (case sensitive)
- regular expressions
- empty ( ), which means "any"
- *, which also means "any" (if you prefer to write that out explicitly)
```

--------------------------------

### Select Markdown sections with mdq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Demonstrates how to use `mdq` to select all sections containing a specific string, 'usage', from a Markdown file piped as input. This is a fundamental operation for filtering content.

```shell
cat example.md | mdq '# usage'
```

--------------------------------

### mdq Selectors for Fenced Code Blocks

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet illustrates the mdq selector syntax for matching fenced code blocks in markdown, including those with language specifiers. It shows how to target both generic and language-specific code blocks.

```text
``` code-block
```language code-block
```

--------------------------------

### mdq JSON Output Flag

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Documents the `--output json` flag (alias `-o json`) for the `mdq` command-line tool. This flag changes the output format of the selected items from Markdown to JSON, providing a structured representation of the query results.

```APIDOC
Flag: --output json
Alias: -o json
Description: Causes mdq to output the selected items as JSON, instead of Markdown.
```

--------------------------------

### mdq Selector with Quoted String Matching

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Demonstrates using quoted strings in `mdq` selectors for case-sensitive substring matching. Highlights the ability to include special characters (like `|`) and escape sequences (`\n`, `\"`, `\u{...}`) within quoted strings.

```shell
# Find sections whose titles contain the text "quoted | strings".
# (You'll see in a sec why the pipe char requires us to quote this.)
$ cat example.md | mdq '# "quoted | strings"'

# Quoted strings can have escape sequences (unquoted strings can't)
$ cat example.md | mdq '# "typical \n \"escape\" \u{2603} sequences" '
```

--------------------------------

### mdq Selector for Raw HTML

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet shows the mdq selector syntax for matching raw HTML content embedded within markdown. It provides a concise way to target non-markdown elements.

```text
</> html
```

--------------------------------

### MDQ Table Selector: Select Entire Table

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Demonstrates the `mdq` table selector syntax to retrieve the entire table. Using `*` for both column and row matchers ensures all columns and all non-header rows are included, along with the header.

```mdq
:-: * :-:
```

--------------------------------

### mdq Selector with Unquoted String Matching

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Illustrates using unquoted strings in `mdq` selectors for case-insensitive substring matching. Notes that leading/trailing whitespace is ignored and it matches against any substring.

```shell
# Find sections whose titles contain the text "unquoted strings".
$ cat example.md | mdq '# unquoted strings'
```

--------------------------------

### Query uncompleted tasks in Markdown with mdq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Demonstrates how to use `mdq` to find uncompleted checklist items (e.g., `'- [ ]'`) within a Markdown document. This functionality is particularly useful for enforcing structured templates, such as those found in GitHub PRs, by identifying incomplete sections.

```shell
mdq '- [ ]'
```

--------------------------------

### mdq JSON Output for Link Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Introduces the general JSON structure for a Markdown link, indicating that its specific properties depend on the link style.

```json
{
  "link": {
    /* see below */
  }
}
```

--------------------------------

### mdq JSON Output Schema

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Defines the comprehensive structure of the JSON output when using the `--output json` (or `-o json`) option in mdq. This schema includes arrays for selected items, and objects for link and footnote references, detailing their properties and usage.

```APIDOC
mdq JSON Output Schema:
  Root Object:
    "items": array of polymorphic objects
      Description: Contains an array of selected items. This entry is always present, but may be empty if there were no selected items. Each item is a polymorphic object.
    "links": object (optional)
      Description: Provides the reference definitions for links and images that use the [text][1] form ONLY for links and images that appear as part of inline text.
      Keys: The reference ids, without square brackets. For example, "1".
      Values: object, with either one or two entries:
        "url": string; the reference URL; always provided.
        "title": string; the reference title, if one exists; omitted if there's no title.
          Example: [1]: https://example.com "this is a title"
      Notes:
        - [collapsed][] and [shorthand] links count as reference links, and will appear in this object.
        - [inline](https://example.com) links will NOT be in this object.
        - If there are no reference-style links, the entire "links" entry will be omitted.
    "footnotes": object (optional)
      Description: Provides the footnote texts for footnotes.
      Keys: The footnote ids, without the square brackets OR the ^. In the example above, the id would be "a".
      Values: array of objects; follow the same syntax as the top-level "items". Since footnote text may contain several top-level blocks, this is an array.
      Example:
        Some text that needs further explanation.[^a]
        [^a]: This is the footnote text. It is _full_ **markdown** and can
          - even
          - include block elements
```

--------------------------------

### mdq JSON Output for Inline Link

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Defines the JSON structure for a Markdown inline link, capturing its display text, URL, and optional title.

```markdown
[Markdown _text_](https://example.com "link title")
```

```json
{
  "display": "Markdown text. Inline elements like _emphasis_ or [links][1] are rendered as Markdown",
  "url": "https://example.com",
  "title": "link title"
}
```

--------------------------------

### Extract and parse ticket URL from Markdown with mdq and jq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Demonstrates a powerful workflow to extract a specific ticket URL from Markdown text. It uses `mdq`'s JSON output option (`--output json`) to structure the extracted data, which is then piped to `jq` for precise parsing and retrieval of the URL.

```bash
TICKET_URL="$(echo "$PR_TEXT"
  | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)'
  | jq -r '.items[].link.url')"
```

--------------------------------

### mdq Selector for Markdown Headers

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Shows how to use `mdq` to find Markdown headers (sections) whose titles contain a specific string. The `#` symbol denotes a header selector.

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

--------------------------------

### mdq JSON Output for Code Block Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Illustrates the JSON structure for a Markdown code block, including its code content, type, language, and optional metadata. It notes that language and metadata are omitted if not present in the original Markdown.

```markdown
```rust metadata string
text of the code block
```
```

```json
{
  "code_block": {
    "code": "text of the code block",
    "type": "code | math | toml | yaml",
    "language": "rust",
    "metadata": "metadata string"
  }
}
```

--------------------------------

### mdq JSON Output for Full Document

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Describes the top-level JSON structure representing an entire Markdown document, which is an array of items.

```json
{
  "document": [
    /* items */
  ]
}
```

--------------------------------

### mdq JSON Output Option

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet shows the mdq command-line option to output results in JSON format. This is useful for integrating mdq's output into other tools or scripts that consume structured data.

```text
-o json
```

--------------------------------

### mdq Section Selector Syntax

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Syntax and behavior of the mdq section selector, which targets sections based on their header title. Includes details on required spacing and matching behavior.

```mdq-syntax
# matcher
```

--------------------------------

### mdq Selector for Paragraphs

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Explains the mdq selector for matching paragraphs. A space is required between 'P:' and the matcher unless the matcher is empty, allowing for precise targeting of paragraph content.

```mdq
P: matcher
```

```mdq
P: hello, world
```

--------------------------------

### Output: MDQ Select Single Column

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

The resulting Markdown table after applying the `mdq` selector `:-: name :-:`. It displays only the 'Name' column with its header and all corresponding data rows.

```markdown
| Name |
|------|
| Foo  |
| Bar  |
| Foot |
```

--------------------------------

### mdq JSON Output for Section Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Defines the JSON structure for a Markdown section, including its depth, title, and an array of body items.

```json
{
  "section": {
    "depth": 1,
    "title": "Markdown text. Inline elements like _emphasis_ or [links][1] are rendered as Markdown.",
    "body": [
      /* items */
    ]
  }
}
```

--------------------------------

### mdq JSON Output for Table Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Outlines the JSON structure for a Markdown table, including column alignments and rows of cell content.

```markdown
| header 1 | header 2 |
|----------|----------|
| hello    | world    |
```

```json
{
  "table": {
    "alignments": [
      "left | right | center | none"
      /* ... */
    ],
    "rows": [
      [
        "header 1",
        "header 2"
      ],
      [
        "hello",
        "world"
      ]
    ]
  }
}
```

--------------------------------

### mdq Task Selector Variants

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Table detailing the specific variants for mdq task selectors, indicating how to match uncompleted, completed, or any task status.

```APIDOC
variant: [ ]
meaning: match only uncompleted tasks

variant: [x]
meaning: match only completed tasks

variant: [?]
meaning: match either
```

--------------------------------

### mdq Quoted String Matching

Source: https://github.com/yshavit/mdq/wiki/Home

This snippet details the behavior of quoted string matching in mdq. It covers support for escape sequences, unicode characters, anchoring, and highlights that quoted strings are case-sensitive and do not trim whitespace.

```text
"quoted text with \" escapes, including \u{2603} unicode"
^"☚ also supports anchors ☛"$
'matches any substring; prefix and trailing whitespace is NOT trimmed'
"Case Sensitive"
```

--------------------------------

### Validate bug report template checkbox with mdq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Illustrates how to use `mdq` with the `-q` (quiet) option to check if a specific checkbox, indicating that existing issues have been searched, is marked as completed in a bug report text. The command exits with 0 if the item is found, or non-zero otherwise, making it suitable for conditional logic in scripts.

```bash
if echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' ; then
  ...
```

--------------------------------

### mdq JSON Output for List Item Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Specifies the JSON structure for a Markdown list item, including its content as an array of items, optional index for ordered lists, and optional checked status for task lists.

```markdown
3. [ ] text
```

```json
{
  "list_item": {
    "item": [
      /* items */
    ],
    "index": 3,
    "checked": false
  }
}
```

--------------------------------

### Output: MDQ Select Columns and Filtered Rows

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

The Markdown table output after applying the `mdq` selector `:-: * :-: buzz`. It includes all columns but only the header row and the data row where 'Description' contains 'the buzz'.

```markdown
| Name | Description |
|------|-------------|
| Bar  | the buzz    |
```

--------------------------------

### Remove macOS quarantine flag from mdq binary

Source: https://github.com/yshavit/mdq/blob/main/README.md

Provides a solution for macOS users encountering issues with downloaded `mdq` binaries due to Apple's quarantine security feature. This command removes the `com.apple.quarantine` extended attribute, allowing the executable to run.

```bash
xattr -d com.apple.quarantine mdq
```

--------------------------------

### mdq Selector for Code Blocks

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Details the mdq selector for matching Markdown code blocks. It supports optional language and content matchers, with specific rules for spacing and backticks. The language matcher also supports regular expressions for more complex filtering.

```mdq
```language-matcher content-matcher
```

```mdq
```
```

```mdq
```rust
```

```mdq
``` "let foo"
```

```mdq
```rust "let foo"
```

```mdq
```/rust|java/
```

--------------------------------

### mdq Markdown Link Reference Reordering

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

By default, mdq reorders and moves link references to the first section where they are used. This ensures that all references are defined before their first appearance in the document, improving readability and adherence to Markdown best practices.

```markdown
# Section one

A [link][1].

[1]: https://example.com/1

# Section two

Note that the link reference (`[1]: `) went in section one, since that's the section that used it.
```

--------------------------------

### mdq Selector for Block Quotes

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Explains the mdq selector for matching block quotes. The space between '>' and the matcher is required, unless the matcher is empty, allowing for flexible matching of block quote content.

```mdq
> matcher
```

```mdq
>
```

```mdq
> hello
```

--------------------------------

### Filter Markdown table to show specific person's on-call schedule with mdq

Source: https://github.com/yshavit/mdq/blob/main/README.md

Shows how to use `mdq` to filter a Markdown table, specifically an on-call schedule, to display only the rows and columns relevant to a particular person (Alice in this case). The command outputs a new Markdown table with the filtered content.

```bash
cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
```

--------------------------------

### mdq JSON Output for Paragraph Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Specifies the JSON representation for a Markdown paragraph, which is a simple string containing the paragraph's text.

```json
{
  "paragraph": "Markdown text. Inline elements like _emphasis_ or [links][1] are rendered as Markdown."
}
```

--------------------------------

### mdq JSON Output for List Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Defines the JSON structure for a Markdown list, which is an array of list item values. It clarifies that the list item value itself does not contain the `list_item` wrapper.

```markdown
1. one
2. two
```

```json
{
  "list": [
    /* list item values, as described below */
  ]
}
```

```json
{
  "list": [
    {
      "index": 1,
      "item": [
        {
          "paragraph": "one"
        }
      ]
    },
    {
      "index": 2,
      "item": [
        {
          "paragraph": "two"
        }
      ]
    }
  ]
}
```

--------------------------------

### mdq Selector for Markdown Block Quotes

Source: https://github.com/yshavit/mdq/wiki/Tutorial

Shows the `mdq` selector for finding Markdown block quotes that contain a specific string. The `>` symbol denotes a block quote selector.

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

--------------------------------

### MDQ Table Selector: Select Single Column

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Shows how to use the `mdq` table selector to extract a specific column ('name') from the table. An empty rows matcher (`:-:`) implies selecting all data rows for the specified column.

```mdq
:-: name :-:
```

--------------------------------

### MDQ Table Selector: Select Columns and Filter Rows

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Illustrates a more complex `mdq` table selection, combining column selection (`*` for all columns) with row filtering. The row matcher `buzz` selects only the data row containing that string, in addition to the header row.

```mdq
:-: * :-: buzz
```

--------------------------------

### mdq JSON Output for Block Quote Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Describes the JSON structure for a Markdown block quote, which is an array of nested items.

```markdown
> Some
>
> Text
```

```json
{
  "block_quote": [
    /* items */
  ]
}
```

--------------------------------

### mdq JSON Output for Thematic Break Element

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Defines the JSON structure for a Markdown thematic break, represented by a null value.

```markdown
   ----
```

```json
{
  "thematic_break": null
}
```

--------------------------------

### MDQ Quoted String Escape Sequences Reference

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Reference table detailing the escape sequences supported within MDQ quoted strings, showing the input sequence and the character it produces. These sequences allow for special characters like quotes, backslashes, newlines, and Unicode characters to be included in strings.

```APIDOC
sequence         | produces
------------------|------------------------------------------------------------------------------------------
\', \"       | ' or ", respectively
\`               | '
\\               | \
\n, \r, \t | newline, carriage return, tab (respectively)
\u{...}        | a single unicode code point; ... is a hex number between 1 and 6 digits (respectively)
```

--------------------------------

### mdq Selector for HTML Elements

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

Describes the mdq selector for matching HTML elements within Markdown. It matches the full tag including angle brackets and applies to both HTML blocks and inlines. Users should note that only tags are rendered as HTML elements by Markdown.

```mdq
</> matcher
```

```markdown
Some <span>inline text
```

```mdq
</> "<span>"
```

--------------------------------

### mdq Markdown Output Thematic Break

Source: https://github.com/yshavit/mdq/wiki/Full-User-Manual

When mdq outputs multiple selected items in Markdown format, they are separated by a thematic break to visually distinguish them.

```markdown
   ---
```
Tokens:
Raw