Skip to content

📝 docs(skills): consolidate processing-markdown skill reference into SKILL.md #1928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
harehare merged 2 commits into from
Jun 24, 2026
Merged

📝 docs(skills): consolidate processing-markdown skill reference into SKILL.md #1928

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
034755f
📝 docs(skills): consolidate processing-markdown skill reference into …
harehare Jun 24, 2026
8c26665
📝 docs(skills): note that mq accepts multiple file args via shell glob
harehare Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 0 additions & 184 deletions skills/processing-markdown/REFERENCE.md
View file
Open in desktop

This file was deleted.

84 changes: 60 additions & 24 deletions skills/processing-markdown/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ mq '.h' file.md # All headings
mq '.h(2)' file.md # h2 only
mq '.code("rust")' file.md # Rust code blocks
mq '.link.url' file.md # All URLs
mq '.yaml | to_text()' post.md # Frontmatter
mq '.yaml | to_text' post.md # Frontmatter

# Filter
mq 'select(.code)' file.md # Only code blocks
Expand All @@ -83,17 +83,21 @@ mq 'select(.h.level <= 2)' file.md # h1 and h2 only
mq 'select(contains("TODO"))' file.md # Nodes with "TODO"

# Transform
mq '.h | to_text()' file.md # Headings as plain text
mq '.h | to_text' file.md # Headings as plain text
mq -U '.code.lang |= "rust"' file.md # Update in place

# Multi-file
mq -A 'pluck(.code.value)' *.md # Collect all code values
mq -S 's"\n---\n"' 'identity()' *.md # Merge with separator
mq -S 's"\n---\n"' 'identity' *.md # Merge with separator

# mq accepts multiple file args directly (shell glob expansion) —
# no need to loop over files in bash:
mq '.h | to_text' *.md work/*.md docs/*.md

# Format conversion
mq -F html 'identity()' file.md # Markdown → HTML
mq -F json '.h | to_text()' file.md # Headings → JSON
mq -I html 'identity()' page.html # HTML → Markdown
mq -F html 'identity' file.md # Markdown → HTML
mq -F json '.h | to_text' file.md # Headings → JSON
mq -I html 'identity' page.html # HTML → Markdown

# Streaming large files
mq --stream 'select(contains("ERROR"))' large.md
Expand All @@ -105,32 +109,64 @@ When using `-I html`, mq converts HTML to Markdown first — use Markdown select

```bash
# WRONG
curl -s https://example.com | mq -I html '.p | to_text()'
curl -s https://example.com | mq -I html '.p | to_text'

# CORRECT
curl -s https://example.com | mq -I html '.text | to_text()'
curl -s https://example.com | mq -I html '.text | to_text'
curl -s https://example.com | mq -I html '.link.url'
curl -s https://example.com | mq -I html '.h | to_text()'
curl -s https://example.com | mq -I html '.h | to_text'
```

## Essential CLI Flags

A small, stable cheat sheet — not exhaustive. See below for everything else.

| Flag | Purpose |
| ----------------------- | ------------------------------ |
| `-A, --aggregate` | Combine inputs into one array |
| `-F, --output-format` | Set output format |
| `-I, --input-format` | Set input format |
| `-U, --update` | Update file in place |
| `-S, --separator` | Insert separator between files |
| `--stream` | Process line by line |
| `mq repl` | Interactive REPL session |

For the full CLI option list (all flags, possible format values, auto-parsing by file extension, `ARGS` handling), run `mq --help`.
For the full built-in function reference (300+ functions with descriptions), run `mq --doc`.

Note: `--args` also accepts the hidden aliases `--arg` and `--define` (not shown in `mq --help`).

## Node Attribute Reference

These attributes are Markdown-selector-specific and are not covered by `mq --doc` / `mq --help`.

| Node | Attributes |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `.h` | `level`/`depth` (1–6), `value` |
| `.code` | `lang`/`language`, `value`, `meta`, `fence` (bool) |
| `.link` | `url`, `title`, `value` |
| `.image` | `url`, `title`, `alt` |
| `.list` | `index`, `level`, `ordered` (bool), `checked` (bool), `value` |
| `.[row][col]` (table cell) | `row`, `column`, `last_cell_in_row` (bool), `last_cell_of_in_table` (bool), `value` |
| `.link_ref` | `ident`, `label` |
| `.image_ref` | `ident`, `label`, `alt` |
| `.footnote_ref` | `ident`, `label` |
| `.footnote` | `ident`, `text` |
| `.definition` | `ident`, `url`, `title`, `label` |
| `.mdx_jsx_flow_element` | `name` |
| `.mdx_flow_expression` | `value` |

## Function Call Syntax

- All function calls require parentheses `()`.
- If a function is called with missing arguments, the piped value (`|`) is used as the first argument.

## Environment Variables

- `__FILE__` — full path to the file being processed
- `__FILE_NAME__` — filename without path
- `__FILE_STEM__` — filename without extension

| Flag | Purpose |
| --------------------- | ----------------------------------------------------- |
| `-A, --aggregate` | Combine all inputs into single array |
| `-I, --input-format` | Input format (see REFERENCE.md for full list) |
| `-F, --output-format` | Output format: `markdown`, `html`, `text`, `json`, `table`, `grep`, `raw`, `none` |
| `-U, --update` | Update file in place |
| `-f, --from-file` | Load query from `.mq` file |
| `-S, --separator` | Insert query result between files |
| `--args NAME VALUE` | Set runtime variable (aliases: `--arg`, `--define`) |
| `--stream` | Process line by line |
| `-C, --color-output` | Colorize output |
| `-P THRESHOLD` | Parallel processing threshold (default: 10) |
| `mq repl` | Start interactive REPL session |

For full CLI options, attribute reference, and function list, see [REFERENCE.md](REFERENCE.md).
For advanced examples, see [EXAMPLES.md](EXAMPLES.md).

## When NOT to Use mq
Expand Down