bmad-shard-doc

To split a large markdown document into smaller files by section, you can use a document sharding process that breaks the content into multiple files based on level 2 headings, creating an index file for easier organization and maintenance.

The best way to organize long markdown documentation for collaborative editing is sharding it into a structured folder of smaller topic files with an index, preventing large architecture docs or handbooks from becoming unmanageable.

You can shard an architecture doc into topic files by validating the source markdown, selecting a destination folder, and executing the npx markdown-tree-parser explode command to generate the section-based output.

You do not need to manually delete the original markdown file after sharding, as the workflow prompts you to either delete, archive, or keep the original document to avoid duplicate source confusion.

You can customize the destination folder when splitting markdown files, as the guided output handling process confirms or allows you to create a specific writable directory before executing the sharding command.

Section splitting handles markdown headings for file organization by defaulting to level 2 headings, automatically dividing the document structure into separate files and verifying the creation of an index.md output.