Skip to content

Output layout and media

Where Markdown files go

The output path is planned for every job before any conversion starts.

Single PDF

--output Result for book.pdf
not given book.md beside the PDF
notes.md notes.md
an existing folder out/ out/book.md
anything else not ending in .md error, exit status 2

The input file must end in .pdf (any letter case). If the input is a symbolic link to a PDF, the link is resolved and the target is converted.

Folder of PDFs

The folder is searched recursively for files ending in .pdf, .PDF and so on. Each PDF maps to the same relative path under --output, with the extension changed to .md. Without --output, each Markdown file goes next to its PDF.

--output is always treated as a folder for folder input, even if its name ends in .md. If --output names an existing file, the run stops with exit status 2.

Symbolic links to folders are not followed, and symbolic links to PDF files inside the tree are skipped. A folder with no PDFs is an error.

Several strategies

When more than one strategy is requested, each output gets a suffix with the requested strategy name:

pdfs/part/book.PDF
  --output markdown
    -> markdown/part/book.md
  --output markdown --strategies=markit,pymupdf --media
    -> markdown/part/book.markit.md
       markdown/part/book.markit/page-0001-001.png
    -> markdown/part/book.pymupdf.md
       markdown/part/book.pymupdf/page-0001-001.png

The suffix names the strategy you asked for, even if a fallback converter wrote the file. The JSON report's strategy field names the converter that actually did.

Media export

With --media (or --media=images), each raster image region shown on a page is rendered to PNG at --dpi. With --media=pages, each selected page is rendered as a whole, which includes vector artwork. The images are rendered pixels: original embedded image formats, editable vectors and exact inline placement are not kept.

The images go into a folder named after the Markdown file's full stem, next to it:

book.md
book/
  .vexy-pdf3md
  page-0001-001.png
  page-0003-001.png
  page-0003-002.png

File names are page-PPPP-NNN.png: the one-based page number in the original PDF, then the image number on that page. A ## Media section is appended to the Markdown, with one relative, URL-escaped link per image:

## Media

![Page 1, image 1](book/page-0001-001.png)

The media folder is created even if no images are found. The .vexy-pdf3md file marks the folder as generated by this package.

Existing files and overwrite

  • Existing Markdown is skipped by default. The result has "status": "skipped" and the exit status stays 0.
  • --overwrite=True replaces the Markdown only after the new conversion has passed the quality checks. If conversion fails, the old file stays.
  • An existing media folder is replaced only with --overwrite=True and only if it contains the .vexy-pdf3md marker. Otherwise the job fails with media directory already exists and is not replaceable. Keep hand-made files outside generated media folders.
  • If installing the new media folder fails, the previous one is restored.

Collision checks

Before converting, the tool rejects plans where:

  • two jobs would write the same path, compared case-insensitively (for example A.pdf and a.PDF in one folder);
  • an output path is the same as an input PDF;
  • an output path is a symbolic link;
  • one output path is inside another job's media folder.

These checks cover one invocation. Do not run two invocations that write the same destinations at the same time.