mdq - Markdown Query

mdq is a command-line tool for searching, filtering, and highlighting content within Markdown files. It allows you to query markdown documents for specific terms and returns results with context, including headings and list items.

Features

• Search for keywords: Easily search for specific keywords within markdown files.
• Highlight results: Search results are highlighted for better visibility using ANSI color codes.
• Contextual results: Display surrounding context around matches, such as parent headings or list items.
• Support for multiple search terms: Search for more than one term at once.
• No dependencies: mdq is built using Python's standard libraries, so it’s easy to set up and use.

Installation

Option 1: Install via pipx (Recommended)

pipx is a great way to install Python applications globally while keeping them isolated from the system environment.

1. Install pipx if it's not already installed:

   sudo apt install pipx
   

2. Install mdq:

   pipx install git+https://git.xle.sh/xle/mdq.git
   

Option 2: Install in a Virtual Environment

1. Create a virtual environment:

   python3 -m venv mdq-env
   

2. Activate the virtual environment:

   source mdq-env/bin/activate
   

3. Install mdq locally: In the root of the repository (where setup.py is):

   pip install .
   

4. Run the mdq command:

   mdq "search term"
   

Option 3: Install Globally (Not Recommended)

If you really want to install mdq globally on your system, you can override the restrictions by running:

sudo pip install . --break-system-packages

Note: This method is not recommended, as it may interfere with system-managed Python packages.

Usage

Once installed, you can use the mdq command to search through markdown files. You can pass one or more search terms, and the results will include the matched content with context.

Basic Search

cat /path/to/your/markdown/files/*.md | mdq search_term

This will search for the term "search_term" in all .md files in the specified directory.

Multiple Search Terms

cat /path/to/your/markdown/files/*.md | mdq search_term_1 search_term_2

This will search for both "search_term_1" and "search_term_2" in the specified markdown files and show the results for both.

Search with Context

By default, the results will show the keyword matches with surrounding context (headings and list items). You can adjust the context size and highlighting options through various flags.

Flags

• --raw: Output results without any highlighting (for raw output).

  Example:

  cat /path/to/your/markdown/files/*.md | mdq --raw search_term
  

• --help: Display help message with available options.

  Example:

  mdq --help
  

Example

If you have a Markdown file like this:

# Tasks

## Deployment

- Set up the production environment
- Set up the staging environment

## Testing

- Test the production system
- Test the staging system

Running the following command:

cat /path/to/your/markdown/file.md | mdq production

Will output something like:

## Deployment
- Set up the **production** environment
- Set up the staging environment

Contributing

Feel free to fork the repository, open issues, and submit pull requests. If you'd like to contribute to the development of mdq, please follow these steps:

1. Fork the repository
2. Create a new branch
3. Make your changes
4. Open a pull request

Code of Conduct

We expect all contributors to follow the project's code of conduct. Please be respectful and considerate when participating in discussions and submitting contributions.

License

mdq is licensed under the MIT License. See the LICENSE file for more information.