Extract sections and code blocks from Markdown files. Pipe into zx to execute them — makes development setup easier and keeps README maintained.
- mdextract — Extract sections from Markdown files to stdout
- mdrun — Thin wrapper around zx for stdin execution (temporary; see below)
npm install -g @gin0606/mdextract# Extract all code blocks as Markdown
mdextract README.md
# Extract a specific section
mdextract README.md -s "Development/Setup"
# List sections
mdextract README.md --list
# Exclude specific subsections
mdextract README.md -s "Development/Setup" --exclude "Build"
# Exclude multiple subsections
mdextract README.md -s "Development/Setup" --exclude "Build" --exclude "Install Dependencies"
# Preview code blocks without output
mdextract README.md --dry-run
mdextract README.md -s "Setup" --dry-run| Option | Description |
|---|---|
-s, --section |
Section path to extract |
-x, --exclude |
Exclude section paths (relative to -s) |
-l, --list |
List sections |
-n, --dry-run |
Show code blocks (no output) |
-h, --help |
Show help |
-v, --version |
Show version |
Note:
mdrunis a temporary workaround. zx currently has a bug that prevents it from reading Markdown via pipe (mdextract ... | npx zx --ext='.md'). This has been fixed but not yet released. Once a zx release includes this fix,mdrunwill be removed and you can usemdextract ... | npx zx --ext='.md'directly.
mdrun reads Markdown from stdin and executes code blocks using zx.
# Pipe mdextract output to mdrun
mdextract README.md -s "Development/Setup" | mdrun
# Execute all code blocks
mdextract README.md | mdrunmdrun uses zx to execute Markdown files. The following code block languages are supported:
| Language tag | Execution |
|---|---|
js, javascript |
Runs as JavaScript |
ts, typescript |
Runs as TypeScript |
bash, sh, shell |
Runs as shell |
| No language tag / other langs | Skipped |
mdextract completion >> ~/.bashrcmdextract completion >> ~/.zshrcmdextract completion --fish > ~/.config/fish/completions/mdextract.fishYou can also run mdextract README.md -s mdextract/Development/Setup | mdrun to install dependencies and build in one go.
pnpm installpnpm buildYou can also run mdextract README.md -s mdextract/Development/Verify | mdrun to run all verification tasks.
pnpm testpnpm typecheckpnpm lintpnpm fmt:checkYou can also run mdextract README.md -s mdextract/Development | mdrun to execute all the development tasks above in order.