md-unzip

Unzip your Markdown. Extract fenced code blocks into files.

md-unzip parses a Markdown document, guesses the intended file path for every fenced code block, and writes the block contents to disk. It supports all common LLM output formats (bold, headings, backticks, XML tags, fence meta, etc.) plus a pluggable strategy system for custom extraction rules.

Install

npm install -g md-unzip
# or
pnpm add -g md-unzip

After installation the md-unzip command is available globally.

Usage

# Basic extraction
md-unzip -i README.md -o ./out

# Dry-run to preview changes
md-unzip -i README.md -o ./out --dry-run

# Only use specific strategies
md-unzip -i README.md -o ./out -s bold,comment-path

# Custom regex strategy
md-unzip -i README.md -o ./out -s regex -r "src/[a-z/]+\\.ts"

# Replace existing files explicitly
md-unzip -i README.md -o ./out --overwrite

# Raise or lower the path confidence threshold (default: 70)
md-unzip -i README.md -o ./out --min-confidence 80

# Verbose mode
md-unzip -i README.md -o ./out -v

Path Resolution Strategies

All enabled strategies contribute path candidates. Candidates are scored by:

• how explicit the marker is (fence metadata and file tags rank above generic text);
• how close the marker is to the code block;
• whether the code language matches the file extension;
• whether multiple strategies independently support the same path.

The highest-confidence path is selected when it reaches --min-confidence. Different paths less than five points apart are considered ambiguous and skipped. Strategy order is used only as a final tie-breaker.

| Strategy | Example Match | |----------|---------------| | fence-meta | ```ts path/to/file.ts | | xml-tag | <file name="path/to/file.ts"> | | heading | ### path/to/file.ts | | backtick-heading | ### `path/to/file.ts` | | heading-bold | ### path/to/file.ts | | file-bold | ### File: path/to/file.ts | | bold | path/to/file.ts | | numbered-bold | 1. path/to/file.ts | | numbered-backtick | 1. `path/to/file.ts` | | colon | path/to/file.ts: | | hash | # path/to/file.ts | | inline-code | `path/to/file.ts` | | path-string | first file-looking path | | regex | user-supplied --regex | | comment-path | // path/to/file.ts (first code line) |

Safety

• Absolute paths in Markdown are relativised to the output directory.
• Directory traversal attempts (e.g. ../escape.ts) are skipped.
• Canonical paths are checked before and after directory creation, blocking symlink escapes.
• Existing files are not overwritten by default; use --overwrite explicitly.
• Duplicate paths in one Markdown document are detected and the first file wins.
• Section directories are not inferred as files by generic path strategies.
• Existing file/directory collisions are skipped with a diagnostic instead of aborting extraction.
• Low-confidence and ambiguous candidates are reported without being written.
• --dry-run shows exactly what would be written without touching disk.

Development

The published CLI supports Node.js 18+. Development and release work require Node.js 22.13+ because pnpm 11 runs on that baseline. Any pnpm >=11 <12 release is accepted.

# With Corepack
corepack pnpm@11 install
corepack pnpm@11 build
corepack pnpm@11 test

Built with esbuild into a single bundled ESM file, compatible with Node.js 18+ on Windows, macOS, and Linux.

License

MIT