Split
Break large markdown files into uploadable parts
split breaks large markdown files into smaller parts at heading boundaries. It preserves YAML frontmatter on every part and adds linking metadata so the parts stay associated. Use it on files that scan flags as oversized.
Usage
Options
| Option | Default | Description |
|---|---|---|
--split-level <n> | 2 | Heading level (1–6) to split at |
--target-size <mb> | 15 | Target maximum size per part (MB) |
--target-chunks <n> | 400 | Target maximum estimated chunks per part |
--suffix <pattern> | -part-{n} | Filename suffix for parts ({n} = part number) |
--only-oversized | false | Only split files that exceed the upload limits below |
--max-file-size <mb> | 20 | Oversized file-size threshold (with --only-oversized) |
--max-chunks <n> | 500 | Oversized chunk-count threshold (with --only-oversized) |
--pattern <glob> | **/*.md | Glob pattern when given a directory |
-r, --recursive | false | Process directories recursively |
-o, --output <dir> | source dir | Output directory for split parts (defaults to the source file's directory) |
--dry-run | false | Preview the split plan without writing files |
-v, --verbose | false | Verbose logging |
How It Works
- The file is split at the chosen heading level (default
##/h2). If a single section still exceeds the target size or chunk count, it is further split at paragraph boundaries. - Each part keeps the original frontmatter, with added linking metadata so the parts remain grouped.
- Parts are named with the
--suffixpattern — e.g.notes-part-1.md,notes-part-2.md.
A 2000-line file with four ## sections splits into roughly four parts, each small enough to upload.
Next Steps
- Scan - Identify which files need splitting
- Batch Upload - Upload the split parts