bmad-shard-doc

Splitting a large markdown document into smaller section files involves sharding level-2 headings into an organized destination folder. The process uses npx @kayvan/markdown-tree-parser explode to generate modular files and an index.md for easy navigation.

Document sharding for markdown knowledge bases is the process of breaking unwieldy, monolithic documentation into modular, section-based files. It solves knowledge-base maintenance issues by creating an organized folder with a structured index for easier updates and section-focused reuse.

Organizing a markdown file into a structured folder requires selecting a writable destination directory and running a markdown tree parser. The tool creates a folder named after the source file and generates an index.md to provide an easy entry point for navigating the sharded sections.

You can delete, archive, or keep the original markdown file after sharding. The process verifies the output files and index.md before handling the original document according to your chosen option, ensuring data safety and preventing accidental loading of the wrong version.

Markdown file sharding validates source existence, markdown file extensions, and destination directory permissions before executing the split. These safety guardrails ensure the command succeeds and verifies produced files before reporting completion.

Markdown section sharding should be used for documentation governance when you need modular navigation, smaller updates, or section-focused reuse without duplicating content. It is ideal for maintaining large knowledge bases where unwieldy, monolithic documents slow down workflow.