/gaia-shard-doc
user-facingWhat it does
/gaia-shard-doc splits a large Markdown document into smaller files, one per section at the chosen heading level. The output is a directory containing the shard files plus an index.md that links to each one. Every byte of the source content is preserved.
When to use it
- A document has grown too large to navigate or edit efficiently.
- You want to break a monolithic document into section-level files for parallel editing.
Prerequisites
- A source file must exist. If not provided as an argument, the command asks which file to shard.
How to invoke
/gaia-shard-doc .gaia/artifacts/planning-artifacts/architecture.md
/gaia-shard-doc .gaia/artifacts/planning-artifacts/prd.md --level=H3What it does step by step
- Load source Reads the source file and counts total lines and sections.
- Parse sections Identifies all sections at the split level (default H2). Content before the first heading becomes
_preamble.md. Generates a filename for each section. - Preview plan Shows the planned file list with per-file line counts. Asks for confirmation.
- Write shards Creates the output directory and writes each shard file plus an index.md with a table of contents.
- Report Reports the number of shards created and verifies total lines equal the source.
Inputs
| Input | Source | Description |
|---|---|---|
source-file | Command argument | Path to the Markdown file to split. |
--level | Flag (optional) | Split level: H1, H2 (default), or H3. |
Outputs
| Output | Location | Description |
|---|---|---|
| Shard files | Output directory (source filename without extension) | One file per section, numbered with a prefix (01-*, 02-*). |
| Index file | Output directory | Table of contents linking to all shards. |
Example session
> /gaia-shard-doc .gaia/artifacts/planning-artifacts/architecture.md
Plan:
_preamble.md 12 lines
01-system-overview.md 48 lines
02-components.md 94 lines
03-data-arch.md 67 lines
index.md auto-generated
Proceed? [y/n] > y
4 shards created. 221 lines distributed (matches source).What to run next
/gaia-merge-docs-- reassemble shards back into a single document./gaia-index-docs-- update the parent directory index.
Troubleshooting
No shard boundaries detected
The source document contains no headings at the split level. No shards are created.
Content inside code blocks
Headings inside fenced code blocks are correctly ignored and do not create false shard boundaries.