Python bindings for the mq Markdown processor.
pip install markdown-queryUse the run function to process Markdown with mq queries:
import mq
# Extract all level 1 headings
result = mq.run(".h1", "# Hello World\n\n## Heading2\n\nText")
print(result.values) # ['# Hello World']
# Extract all level 2 headings
result = mq.run(".h2", "# Main Title\n\n## Section A\n\n## Section B")
print(result.values) # ['## Section A', '## Section B']
# Get all results as a single string
print(result.text) # '## Section A\n## Section B'Use mq query syntax to filter and transform Markdown:
import mq
markdown = """
# Product
## Features
Great features here.
## Installation
Install instructions.
"""
# Filter headings containing specific text
result = mq.run('.h2 | select(contains("Feature"))', markdown)
print(result.values) # ['## Features']
# Extract list items
result = mq.run(".[]", "# List\n\n- Item 1\n- Item 2\n- Item 3")
print(result.values) # ['- Item 1', '- Item 2', '- Item 3']
# Extract code blocks
result = mq.run(".code", "# Code\n\n```python\nprint('Hello')\n```")
print(result.values) # ["```python\nprint('Hello')\n```"]mq supports multiple input formats:
import mq
# Markdown (default)
options = mq.Options()
options.input_format = mq.InputFormat.MARKDOWN
result = mq.run(".h1", "# Heading", options)
# MDX (Markdown with JSX)
options = mq.Options()
options.input_format = mq.InputFormat.MDX
result = mq.run("select(is_mdx())", "# MDX\n\n<Component />", options)
print(result.values) # ['<Component />']
# HTML
options = mq.Options()
options.input_format = mq.InputFormat.HTML
result = mq.run('select(contains("Hello"))', "<h1>Hello</h1><p>World</p>", options)
print(result.values) # ['# Hello']
# Plain text
options = mq.Options()
options.input_format = mq.InputFormat.TEXT
result = mq.run('select(contains("2"))', "Line 1\nLine 2\nLine 3", options)
print(result.values) # ['Line 2']Available input formats:
InputFormat.MARKDOWN- Standard Markdown (default)InputFormat.MDX- Markdown with JSXInputFormat.HTML- HTML contentInputFormat.TEXT- Plain textInputFormat.RAW- Raw string inputInputFormat.NULL- Null input
Customize the output rendering:
import mq
options = mq.Options()
options.input_format = mq.InputFormat.MARKDOWN
options.list_style = mq.ListStyle.PLUS # Use '+' for list items
options.link_title_style = mq.TitleSurroundStyle.SINGLE # Use single quotes for link titles
options.link_url_style = mq.UrlSurroundStyle.ANGLE # Use angle brackets for URLs
result = mq.run(".", markdown, options)Available options:
ListStyle:DASH(default),PLUS,STARTitleSurroundStyle:DOUBLE(default),SINGLE,PARENUrlSurroundStyle:NONE(default),ANGLE
Convert HTML to Markdown:
import mq
html = "<h1>Hello World</h1><p>This is a <strong>test</strong>.</p>"
markdown = mq.html_to_markdown(html)
print(markdown) # '# Hello World\n\nThis is a **test**.'
# With conversion options
options = mq.ConversionOptions()
options.extract_scripts_as_code_blocks = True # Convert <script> tags to code blocks
options.generate_front_matter = True # Generate front matter from metadata
options.use_title_as_h1 = True # Use <title> as h1 heading
markdown = mq.html_to_markdown(html, options)The run function returns an MQResult object:
import mq
result = mq.run(".h", "# H1\n\n## H2\n\n### H3")
# Get the number of results
print(len(result)) # 3
# Access individual results by index
print(result[0].text) # '# H1'
# Iterate over results
for value in result.values:
print(value)
# Get all results as a single string
print(result.text) # '# H1\n## H2\n### H3'
# Check if a value is in the result
print("# H1" in result.values) # TrueEach MQValue has the following properties:
text- The string representation of the valuevalues- For arrays, returns the list of valuesmarkdown_type- The type of Markdown element (e.g.,Heading,Code,List)is_array()- Check if the value is an arrayis_markdown()- Check if the value is a Markdown element
Invalid queries raise a RuntimeError:
import mq
try:
result = mq.run(".invalid!!!", "# Heading")
except RuntimeError as e:
print(f"Query error: {e}")git clone https://github.com/harehare/mq
cd mq/crates/mq-python
pip install maturin
maturin developpytest tests/Licensed under the MIT License.