Split a document into chunks at a heading level

Goal: Break a long document into standalone chunks wherever a heading of a given level appears — useful for feeding sections to an LLM one at a time, or generating one output file per chunk downstream.

Prerequisites: The section module, via -A or nodes.

Query

$ mq -A 'section::split(2)' README.md

Input

# Chapter 1

Intro.

## Section 1.1

Detail 1.1

## Section 1.2

Detail 1.2

# Chapter 2

Content.

## Section 2.1

Detail 2.1

Output

## Section 1.1

Detail 1.1

## Section 1.2

Detail 1.2

# Chapter 2

Content.

## Section 2.1

Detail 2.1

Notes

• Gotcha: content before the first heading at the split level is dropped — here, # Chapter 1 and Intro. disappear because they precede the first ##. Once the first split point is found, every following heading (at or above that level) starts a new chunk normally, which is why # Chapter 2 survives. If you need that leading content preserved, prepend it to the output yourself, or split at level 1 instead.
• split(1) on the same input is a no-op here, since every section is already anchored under a level-1 heading.
• section::collect (flattening section objects back to plain Markdown nodes) isn’t needed for CLI output — mq expands section objects to Markdown automatically there. It’s only required when consuming section objects from Rust or other embedding code; see the equivalent note in Extract a section by its heading.