DEV Community

Cover image for mq: The Missing Link Between jq and Markdown
Takahiro Sato
Takahiro Sato

Posted on

mq: The Missing Link Between jq and Markdown

#markdown #cli #ai #llm

Transform Markdown with the power of jq-like queries

Introduction

Have you ever found yourself needing to extract specific content from Markdown files, manipulate documentation structures, or process content for LLM workflows? If you're familiar with jq for JSON processing, you'll love mq - a powerful command-line tool that brings the same level of querying sophistication to Markdown documents.

Demo

What is mq?

mq is a Rust-based command-line tool that processes Markdown using a syntax similar to jq. It allows you to slice, filter, map, and transform Markdown content with ease, making it an essential tool for developers working with documentation, content management, and modern AI workflows.

Why mq Matters

In today's development landscape, Markdown is everywhere:

  • Documentation: README files, API docs, technical specifications
  • LLM Workflows: Processing prompts and outputs for AI applications
  • Content Management: Blog posts, articles, and knowledge bases
  • Static Site Generation: Processing content for Jekyll, Hugo, and similar tools

Traditional text processing tools like grep, sed, and awk work at the text level, but Markdown has structure that these tools can't understand. mq understands Markdown's semantic structure, allowing you to work with headers, code blocks, lists, and tables as first-class objects.

Getting Started

Installation

The easiest way to install mq is through Cargo:

cargo install --git https://github.com/harehare/mq.git mq-cli --tag v0.2.7
Enter fullscreen mode Exit fullscreen mode

For other installation methods, including Homebrew, Docker, and pre-built binaries, check the official installation guide.

Your First Query

Let's start with a simple example. Create a file called example.md:


# My Project

This is a sample project with multiple sections.

## Features

- Fast processing
- Easy to use
- Extensible

## Code Examples

``javascript
console.log("Hello, World!");
``

``python
print("Hello, World!")
``

## Installation

Run the following command:jj

``bash
npm install my-project
``
Enter fullscreen mode Exit fullscreen mode

Now, let's extract all the code blocks:

mq '.code' example.md
Enter fullscreen mode Exit fullscreen mode

This will output all code blocks from the file. The .code selector specifically targets code block elements in the Markdown structure.

Basic Selectors

mq provides several built-in selectors:

  • .code - Select all code blocks
  • .h1, .h2, .h3, etc. - Select headers by level
  • .[] - Select list items
  • .[][] - Select table cells

Let's try a few more examples:

# Extract all headers
mq '.h' example.md

# Extract only level 2 headers
mq '.h2' example.md

# Extract all list items
mq '.[]' example.md

# Extract JavaScript code blocks only
mq '.code("javascript")' example.md
Enter fullscreen mode Exit fullscreen mode

Filtering and Transforming

One of mq's strengths is its ability to filter and transform content:

# Find headers containing "install"
mq '.h | select(contains("install"))' example.md

# Convert all headers to text
mq '.h | to_text()' example.md

# Extract code blocks and convert to text
mq '.code | to_text()' example.md
Enter fullscreen mode Exit fullscreen mode

Practical Examples

Generate Table of Contents 

mq 'select(or(.h1, .h2, .h3)) | let link = to_link(add("#", to_text(self)), to_text(self), "") | if (is_h1()): to_md_list(link, 1) elif (is_h2()): to_md_list(link, 2) elif (is_h3()): to_md_list(link, 3) else: None' example.md
Enter fullscreen mode Exit fullscreen mode

Extract All Code Examples 

mq '.code | to_text()' example.md
Enter fullscreen mode Exit fullscreen mode

Find Specific Content 

# Find all sections mentioning "installation"
mq 'select(contains("installation"))' example.md
Enter fullscreen mode Exit fullscreen mode

Interactive Development

For experimentation and learning, mq provides a REPL (Read-Eval-Print Loop):

mq repl
Enter fullscreen mode Exit fullscreen mode

This allows you to interactively test queries and explore your Markdown structure.

IDE Support

mq comes with excellent tooling support:

  • VSCode Extension: Available on the Visual Studio Marketplace
  • Language Server Protocol (LSP): For custom function development
  • Syntax Highlighting: For .mq files

What's Next?

This introduction covers the basics of mq, but there's much more to explore:

  • Advanced selectors and filtering
  • Custom functions and modules
  • Batch processing multiple files
  • Integration with CI/CD pipelines
  • Web API and Python bindings

mq transforms how you work with Markdown, making complex document processing tasks simple and intuitive. Whether you're managing documentation, processing content for AI workflows, or building content pipelines, mq provides the tools you need.

Resources

Start exploring mq today and discover how it can streamline your Markdown workflows!

Support

Top comments (0)