Batch Conversion

all2md has first-class support for converting many documents in a single command: glob and directory inputs, parallel workers, output-tree control, and per-file attachment handling. This page is the detailed reference for the batch workflow from the command line. For a quick taste, see the batch section of the Quick Start Guide.

When to Use Built-in Batch 

Reach for the built-in batch features (rather than a hand-written Python loop) when you want parallelism, structure-preserving output, progress reporting, and consistent attachment handling without writing glue code:

all2md '**/*.pdf' --output-dir converted/ --preserve-structure --attachment-mode save -p 3

If you need programmatic control over each file, the Python API loop shown in the Quick Start Guide remains available; everything below is about the CLI.

Selecting Input Files 

Inputs can be one or more paths, glob patterns, or directories:

# Explicit glob (quote it so your shell doesn't expand it first)
all2md '**/*.pdf' --output-dir converted/

# A directory, processed recursively
all2md ./documents --recursive --output-dir converted/

# Multiple inputs mixed together
all2md report.pdf ./more-docs '*.docx' --output-dir converted/

Filtering and exclusion:

# Skip patterns (repeatable)
all2md ./project --recursive --exclude '*.tmp' --exclude '__pycache__' --output-dir converted/

# Include dot-files / dot-folders (skipped by default)
all2md ./project --recursive --include-hidden --output-dir converted/

# Drive the list from a file (one path per line; '#' comments; '-' reads stdin)
all2md --batch-from-list files.txt --output-dir converted/

Tip

Quote glob patterns ('**/*.pdf') so all2md performs the expansion consistently across shells, including recursive ** matching.

Output Location and Structure 

--output-dir writes one Markdown file per input. By default all outputs are placed flat in that directory. --preserve-structure mirrors the input tree relative to the common parent of the inputs:

# Inputs                          # all2md '**/*.pdf' --output-dir converted/ --preserve-structure
docs/                             converted/
  guide/intro.pdf                   guide/intro.md
  guide/setup.pdf                   guide/setup.md
  ref/api.pdf                       ref/api.md

Control the output extension and target format with --output-format and --output-extension (the latter is mostly useful for non-Markdown targets or custom suffixes).

Attachments in Batch Mode 

With --attachment-mode save, images and embedded files are written to disk instead of being inlined. Two layouts are available:

Default (no structure preservation). Attachments for every document are written to a single attachments/ folder relative to the current directory:

all2md '*.pdf' --output-dir converted/ --attachment-mode save

Near-source layout (with –preserve-structure). When you preserve structure and do not set --attachment-output-dir explicitly, all2md co-locates attachments with their output files: each output directory gets a shared .attachments folder, and the Markdown links to it with a relative path so the documents are portable:

all2md '**/*.pdf' --output-dir converted/ --preserve-structure --attachment-mode save

converted/
  sub/
    report.md          # links read ![](.attachments/report_img1.png)
    memo.md
    .attachments/
      report_img1.png
      memo_img1.png

This near-source behavior triggers only when all of these hold: --preserve-structure is set, the attachment mode is save, an --output-dir is given, and neither --attachment-output-dir nor --attachment-base-url was passed explicitly.

Explicit override. Passing --attachment-output-dir always wins and disables the near-source layout — every attachment goes to the directory you name:

all2md '**/*.pdf' --output-dir converted/ --preserve-structure \
    --attachment-mode save --attachment-output-dir ./assets

See Attachment Handling for the full attachment model, filename templates, deduplication, and the other save-mode options.

Parallelism and Error Handling 

--parallel / -p converts files concurrently across worker processes:

all2md '**/*.pdf' --output-dir converted/ -p 3   # 3 workers
all2md '**/*.pdf' --output-dir converted/ -p     # auto-detect worker count

By default the batch stops on the first failure. --skip-errors keeps going and reports the failures in the summary at the end:

all2md ./documents --recursive --output-dir converted/ --skip-errors

Combining Into a Single Document 

Batch conversion writes one output per input. To merge inputs into a single document instead, use --collate (concatenate) or --merge-from-list (ordered merge with optional section titles and a generated table of contents):

all2md chapter_*.pdf --collate --out book.md

These are documented in Command Line Interface; they are a distinct workflow from per-file batch conversion.

Interactive Walkthrough: `all2md batch`

If you would rather be guided through the options, run the interactive batch wizard:

all2md batch

It walks you through five steps — choosing and previewing the input files, the output location and structure, attachment handling, a few file-type-specific options for the formats it detects, and advanced parameters such as worker count. At the end it prints the equivalent all2md ... command (so you can save or reuse it) and offers to run it.

Note

The wizard uses the optional Rich UI. If it is not installed, run pip install 'all2md[cli_extras]' (or uv pip install 'all2md[cli_extras]') for the best experience; a plain-text fallback is used otherwise.