bmad-shard-doc

To split a large markdown document into smaller files by section, you provide a source markdown file and a writable destination folder. The process uses level 2 headings to break the document into organized shards while preserving section order.

The best way to break down long technical planning documents for easier navigation is sharding. This process separates oversized markdown files into modular, indexed files based on level 2 headings, reducing maintenance friction and making sections easy to find.

To shard a markdown file using npx @kayvan/markdown-tree-parser, you need a source markdown file and a destination folder. The parser generates indexed output, creating separate files for each level 2 section while maintaining the original document order.

Yes, you can split markdown documents into level 2 section shards without losing the original heading order. The sharding process generates indexed output in the destination folder that preserves the exact sequence of sections from the source document.

Splitting markdown files into separate shards requires npx @kayvan/markdown-tree-parser to generate the indexed output. You also need a source markdown file to read from and a writable destination folder to store the resulting section files.

You should not use level 2 heading based sharding for markdown files that lack structured headings or contain short content. This approach is designed for long technical, planning, and reference documents that require modular organization for easier review and maintenance.