mdextract

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)

Install

npm install -g @gin0606/mdextract

Usage

mdextract CLI

# 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

Options

| 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 |

mdrun CLI

Note: mdrun is 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, mdrun will be removed and you can use mdextract ... | 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 | mdrun

Supported Code Blocks

mdrun 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 |

Shell Completion

Bash

mdextract completion >> ~/.bashrc

Zsh

mdextract completion >> ~/.zshrc

Fish

mdextract completion --fish > ~/.config/fish/completions/mdextract.fish

Development

Setup

You can also run mdextract README.md -s mdextract/Development/Setup | mdrun to install dependencies and build in one go.

Install Dependencies

pnpm install

Build

pnpm build

Verify

You can also run mdextract README.md -s mdextract/Development/Verify | mdrun to run all verification tasks.

Run Tests

pnpm test

Type Check

pnpm typecheck

Lint

pnpm lint

Format

pnpm fmt:check

You can also run mdextract README.md -s mdextract/Development | mdrun to execute all the development tasks above in order.