mdqy 0.1.3

jq for markdown: query and transform Markdown with a hybrid selector and jq DSL
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# mdqy

jq for markdown. Query markdown documents with a hybrid selector +
jq-style DSL. Rewrite them in place. Pretty render to a terminal.

![demo](examples/demo.gif)

## Install

Homebrew (macOS, Linux):

```sh
brew install pawelb0/tap/mdqy
```

Scoop (Windows):

```sh
scoop bucket add pawelb0 https://github.com/pawelb0/scoop-bucket
scoop install pawelb0/mdqy
```

Shell installer (Unix):

```sh
curl -sSfL https://github.com/pawelb0/mdqy/releases/latest/download/mdqy-installer.sh | sh
```

PowerShell installer (Windows):

```powershell
irm https://github.com/pawelb0/mdqy/releases/latest/download/mdqy-installer.ps1 | iex
```

From crates.io:

```sh
cargo install mdqy --features tty
```

Prebuilt binaries for every release: [github.com/pawelb0/mdqy/releases/latest](https://github.com/pawelb0/mdqy/releases/latest).
On macOS, direct downloads need `xattr -d com.apple.quarantine ./mdqy`
once before first run.

The `tty` feature pulls mdcat in for terminal rendering. Default
builds emit markdown or JSON.

## Documentation

- [quickstart](docs/quickstart.md): tutorial walkthrough. Start here.
- [language](docs/language.md): the jq-style query language.
- [selectors](docs/selectors.md): `hN`, `:pseudos`, `#` sugar, the `>` combinator.
- [transforms](docs/transforms.md): `|=`, `del`, `walk`, `-U`, `--dry-run`.
- [architecture](docs/architecture.md): pipeline, modules, the two evaluators, byte-exact round-trip.

## Usage

```
mdqy '<EXPR>' [PATH...]
```

Paths can be files or directories. Directories walk recursively and
honour `.gitignore`, `.ignore`, and hidden-file rules.

### Query examples

```sh
mdqy '.' README.md                       # identity, byte-exact
mdqy 'headings | .text' README.md        # each heading, plaintext
mdqy 'headings | select(.level == 1) | .text' docs/
mdqy 'h1:first | .text' README.md        # first H1
mdqy 'codeblocks | .lang' README.md      # languages of fenced blocks
mdqy 'links | .href' README.md
mdqy 'section("Install")' README.md      # the Install section back out
mdqy '# Install > codeblocks:first | .literal' tutorial.md  # combinator
mdqy '.. | select(type == "heading")' README.md
```

### Output format

Default is `auto`:

- stdout is a terminal + `tty` feature compiled in → render
- stdout is piped → raw markdown (Node results) or JSON (scalars)

Override with `--output md | json | tty | text`.

### Transforms

```sh
mdqy --dry-run \
     '(.. | select(type == "link")).href |= sub("http:"; "https:")' \
     README.md

mdqy -U 'del((.. | select(type == "image")).title)' docs/
```

`-U` writes in place via atomic rename. `--dry-run` prints a
unified diff and exits 0.

### Multi-file

```sh
mdqy 'headings | .text' docs/           # per-file by default
mdqy --slurp '[.[] | headings | .text] | length' docs/
mdqy --merge 'codeblocks | select(.lang == "rust")' docs/
```

## Library use

```rust
use mdqy::{parse, Query};

let q = Query::compile("headings | .text")?;
for v in q.run_tree(&parse(source)) {
    println!("{:?}", v?);
}
```

See [docs.rs/mdqy](https://docs.rs/mdqy) for the full API.

## Tooling

```sh
cargo run --example gen_completions -- bash > mdqy.bash
cargo run --example gen_manpage > mdqy.1
cargo run --example export_schema --features schema-export > node.schema.json
```

## License

MPL-2.0. See `LICENSE`.