https://github.com/harehare/mq-tui
mq-tui is a Text-based User Interface for the mq Markdown processor.
https://github.com/harehare/mq-tui
markdown mq tui
Last synced: about 1 month ago
JSON representation
mq-tui is a Text-based User Interface for the mq Markdown processor.
- Host: GitHub
- URL: https://github.com/harehare/mq-tui
- Owner: harehare
- License: mit
- Created: 2025-10-19T13:41:03.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-11-25T13:00:36.000Z (about 2 months ago)
- Last Synced: 2025-11-28T18:30:21.268Z (about 1 month ago)
- Topics: markdown, mq, tui
- Language: Rust
- Homepage: https://mqlang.org
- Size: 387 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
mq-tui
[](https://github.com/harehare/mq-tui/actions/workflows/ci.yml)
[](https://github.com/harehare/mq)
Interactive terminal interface for querying and manipulating Markdown content
## Overview
`mq-tui` is a Text-based User Interface for the [mq](https://github.com/harehare/mq) Markdown processor. It provides an interactive terminal experience for querying, filtering, and exploring Markdown documents using the mq query language.
### Key Features
- 🔍 **Interactive Query Mode** - Real-time Markdown querying with instant results
- 🌳 **Tree View** - Visual exploration of Markdown document structure
- ⚡ **Vim-style Navigation** - Efficient keyboard shortcuts (j/k, hjkl)
- 📋 **Clipboard Integration** - Copy results directly to clipboard
- 🎨 **Syntax Highlighting** - Color-coded display of different Markdown elements
- 📖 **Detail View** - Inspect individual elements in depth
- 🔄 **Query History** - Navigate through previous queries
- 🎯 **fx-inspired UX** - Familiar interface for JSON query tool users
## Installation
### Using the Installation Script (Recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/harehare/mq-tui/main/bin/install.sh | bash
# Install from crates.io
cargo install mq-tui
# Install using binstall
cargo binstall mq-tui@0.1.3
```
The installer will:
- Download the latest release for your platform
- Verify the binary with SHA256 checksum
- Install to `~/.mq-tui/bin/`
- Update your shell profile (bash, zsh, or fish)
After installation, restart your terminal or run:
```bash
source ~/.bashrc # or ~/.zshrc, or ~/.config/fish/config.fish
```
### From Source
```bash
git clone https://github.com/harehare/mq-tui.git
cd mq-tui
cargo build --release
# Binary will be at target/release/mq-tui
```
### Supported Platforms
- **Linux**: x86_64, aarch64
- **macOS**: x86_64 (Intel), aarch64 (Apple Silicon)
- **Windows**: x86_64
## Usage
### Basic Usage
```bash
# Open a Markdown file
mq-tui README.md
```
### Query Examples
Once in the TUI, press `:` to enter query mode and try these queries:
```mq
# Select all headings
.h
# Select level 2 headings
.h | select(.depth == 2)
# Select all links
.link
# Select code blocks with specific language
.code | select(.lang == "rust")
# Select list items
.list
# Complex filtering
.h | select(.depth >= 2 and .depth <= 3)
```
## Key Bindings
### Normal Mode
| Key | Action |
| ----------- | ------------------------------------ |
| `q` / `Esc` | Quit the application |
| `:` | Enter query mode |
| `?` / `F1` | Show help screen |
| `t` | Toggle tree view mode |
| `d` | Toggle detail view for selected item |
| `y` | Copy results to clipboard |
| `Ctrl+L` | Clear current query |
### Navigation
| Key | Action |
| ---------- | -------------------- |
| `↑` / `k` | Move up |
| `↓` / `j` | Move down |
| `PageUp` | Page up (10 items) |
| `PageDown` | Page down (10 items) |
| `Home` | Jump to first item |
| `End` | Jump to last item |
### Query Mode
| Key | Action |
| ---------------------- | --------------------------------------- |
| `Enter` | Execute query and return to normal mode |
| `Esc` | Exit query mode without executing |
| `↑` / `↓` | Navigate query history |
| `←` / `→` | Move cursor in query string |
| `Home` / `End` | Jump to start/end of query |
| `Backspace` / `Delete` | Edit query text |
### Tree View Mode
| Key | Action |
| ----------------- | -------------------- |
| `↑` / `k` | Move up in tree |
| `↓` / `j` | Move down in tree |
| `Enter` / `Space` | Expand/collapse node |
| `Esc` / `t` | Exit tree view |
| `?` / `F1` | Show help |
## Modes
### Normal Mode
Default mode for navigating and viewing query results. Use arrow keys or Vim-style navigation to browse through results.
### Query Mode
Activated by pressing `:`. Type your mq query and press Enter to execute. The query is evaluated in real-time as you type.
### Tree View Mode
Activated by pressing `t`. Displays the Markdown document structure as an expandable tree, showing the hierarchy of headings, lists, and other elements.
### Help Mode
Activated by pressing `?` or `F1`. Displays all available keyboard shortcuts and commands.
## Features in Detail
### Real-time Query Execution
Queries are executed as you type, providing immediate feedback and results.
### Detail View
Press `d` to toggle between list view and split view. In split view, the left pane shows the result list while the right pane displays detailed information about the selected item.
### Query History
All executed queries are saved in history. Use `↑` and `↓` in query mode to navigate through previous queries.
### Clipboard Support
Press `y` to copy the current query results to your system clipboard in Markdown format.
### Tree Visualization
The tree view mode provides a visual representation of your Markdown document's structure, with color-coded elements:
- 🔵 **Blue**: Headings
- 🟢 **Green**: Lists
- 🔴 **Red**: Math expressions
- 🟣 **Magenta**: Links
- 🟡 **Yellow**: Images
- 🔵 **Cyan**: Code blocks
## Configuration
`mq-tui` works out of the box with sensible defaults. The UI adapts to your terminal's color scheme and size.
## Related Projects
- [mq](https://github.com/harehare/mq) - The underlying Markdown query processor
- [mq-view](https://github.com/harehare/mq-view) - Markdown viewer with syntax highlighting
- [mqlang.org](https://mqlang.org) - Documentation and language reference
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## License
This project is licensed under the MIT License - see the LICENSE file for details.