Input and Output Behavior

How mq reads Markdown and writes it back, and the options that change it. For the full list of flags, see the CLI reference.

Output formats

-F / --output-format selects how results are written. The default is markdown. Each result is a Markdown node, a string, a number, a boolean, None, an array or a dict. The examples use -I null to show non-Markdown values.

Scalars, None and nested values

None is written as null by json, jsonl, gron and toon, as ~ by yaml, as an empty element by xml, and as an empty string by markdown, text, html, raw, grep, csv and shell.

Arrays and dicts are written as JSON-like text by markdown, text, html and raw. json, jsonl, toml, toon, xml and yaml keep the structure. csv and table use dict keys as columns, and csv writes a nested value as a JSON string in one cell. gron and shell flatten the structure into paths (json.l[0] and l_0).

$ mq -I null -F json '{"k": "v", "n": None, "l": [1, 2]}'
{
  "k": "v",
  "n": null,
  "l": [
    1,
    2
  ]
}
$ mq -I null -F yaml '{"k": "v", "n": None, "l": [1, 2]}'
k: v
"n": ~
l:
  - 1
  - 2
$ mq -I null -F gron '{"k": "v", "l": [1, 2]}'
json = {};
json.k = "v";
json.l = [];
json.l[0] = 1;
json.l[1] = 2;
$ mq -I null -F shell '{"k": "v", "l": [1, 2]}'
k=v
l_0=1
l_1=2

toml needs a dict at the top level and fails on anything else, because a TOML document is a table.

raw

-F raw is the equivalent of jq -r. A string is written without quotes, and each value is followed by a newline. Empty nodes, such as the non-matches of a selector, are skipped. A Bytes value (see to_bytes) is written as is, with no newline, so binary output stays exact.

$ mq -F raw '.h' doc.md
# One
## Two
$ mq -I null -F raw 'to_bytes("a")' | od -c
0000000   a

A Markdown node is written as its Markdown source. For its plain text, use -F text.

Options

HTML output

-F html renders the result as HTML.

Callouts

A block quote that starts with [!TYPE] is a callout. It becomes a div with the class callout and the type in data-callout. A fold marker (- or +) makes it a details element instead, open when the marker is +.

> [!NOTE] Title
> body

> [!TIP]- Folded
> hidden

<div class="callout" data-callout="note">
  <div class="callout-title">Title</div>
  <div class="callout-content">
    <p>body</p>
  </div>
</div>
<details class="callout" data-callout="tip">
  <summary class="callout-title">Folded</summary>
  <div class="callout-content">
    <p>hidden</p>
  </div>
</details>

Wikilinks and embeds

[[target]] and [[target|text]] become links with the class internal-link. The target is used as the href as written. ![[target]] becomes an img, audio, video or embed element when the file is an image, audio, video or PDF, and a link with the classes internal-link embed for a note.

Raw HTML

Raw HTML in the input is kept, except for the tags that GFM filters: <script>, <style>, <textarea> and a few others. These are escaped and show up as text.

<script>alert(1)</script>

<script>alert(1)</script>

Color

--color=WHEN controls whether Markdown output is colorized. WHEN is one of:

-C alone is the same as --color=always, and --color-output is an alias of --color. NO_COLOR overrides always. See Environment Variables for NO_COLOR and MQ_COLORS.

mq '.h' README.md               # colored on a terminal, plain when piped
mq -C '.h' README.md | less -R  # force color
mq --color=never '.h' README.md # no color

List style

Without --list-style, each list keeps the marker it was written with (-, + or *). Pass --list-style dash, plus or star to write every list with one marker.

$ printf '* a\n* b\n' | mq '.'
* a
* b
$ printf '* a\n* b\n' | mq --list-style dash '.'
- a
- b

The listStyle option of mq-web and mq-nodejs works the same way: leave it out to keep the markers.

Frontmatter

A document that starts with a --- line (or +++) and has a closing line is read with frontmatter. The frontmatter is not part of the rendered HTML, and .yaml and .toml select it.

Pass --no-frontmatter for a document that only happens to start with ---, such as one that opens with a horizontal rule. The lines are then read as Markdown: the first --- is a rule, and the text up to the next --- is a paragraph or a heading.

$ cat doc.md
---
not: frontmatter
---
body
$ mq '.' doc.md
---
not: frontmatter
---
body
$ mq --no-frontmatter '.' doc.md
---
## not: frontmatter
body

--no-frontmatter applies to Markdown and MDX input.

Exit codes

Exit codes follow jq. halt(code) exits with code.

With -e / --exit-status the exit code also reflects the result:

None, "", [], {} and a non-matching select() are empty. Other values, including false and 0, are results.

mq -e 'select(.h2)' doc.md || echo "exit: $?"