hammerdown

hammerdown converts PDF, Word, Excel, PowerPoint, and plain-text documents to Markdown. PDF conversion uses PyMuPDF and PyMuPDF4LLM; source images are extracted into the output folder and Markdown image references are generated.

Table of Contents

• Installation
  • Recommended: Python package (pip)
  • Direct Download (Standalone binaries)
  • Context menu integration
• Usage
• Supported Formats
• Output Structure
• Contributing

Installation

Recommended: Python package (pip)

If Python (3.10+) is installed on your system, installing via pip is the recommended method:

pip install hammerdown

Or after cloning the repository locally:

git clone https://github.com/sergeypugin/hammerdown.git
cd hammerdown
pip install .

Direct Download (Standalone binaries)

If you do not have Python installed, precompiled standalone binaries are available on the GitHub Releases page or you can download directly from the links below:

OS	Download
Windows
Linux
macOS

On Linux and macOS, make the downloaded binary executable before running:

chmod +x ./hammerdown-linux-x64
./hammerdown-linux-x64 --version

Context menu integration

Run --install to register file manager integrations, or --uninstall to remove them:

hammerdown --install

What happens on each platform:

• windows: moves binary or script into %LOCALAPPDATA%\Programs\hammerdown\ and adds a "Hammer down file" context menu item for PDF files in Windows Explorer
• linux: creates launcher in ~/.local/bin/hammerdown and Nautilus script in ~/.local/share/nautilus/scripts/Hammer down file
• macOS: creates launcher in ~/.local/bin/hammerdown

Update hammerdown to the latest version at any time:

hammerdown --update

This installer is local and does not require administrator privileges.

Usage

Convert one or several supported files:

hammerdown document.pdf
hammerdown report.docx workbook.xlsx slides.pptx

Files can also be dragged onto the executable. Running hammerdown without file arguments opens a file-selection dialog when a graphical desktop is available. --quiet suppresses routine status messages, which is used by file-manager integrations:

hammerdown --quiet document.pdf
hammerdown --force document.pdf
hammerdown --version
hammerdown --help

Supported Formats

Supported document extensions:

• PDF & E-books: .pdf, .epub, .mobi, .fb2, .xps
• Word: .docx, .doc (legacy .doc via LibreOffice / MS Word)
• Excel: .xlsx, .xls (legacy .xls via LibreOffice / MS Excel)
• PowerPoint: .pptx, .ppt (legacy .ppt via LibreOffice / MS PowerPoint)
• Plain text & tabular: .txt, .md, .log, .csv

Output Structure

For each input file, an output folder MD_<name>_<ext> is written next to the source document:

document.pdf
MD_document_pdf/
├── document.md
└── images/
    └── extracted illustration and embedded document images

Output folder names consistently include the file extension suffix (for example, MD_report_doc/ and MD_report_docx/) to prevent conflicts between different document formats with the same base name.

Images embedded in PDF, Word, or PowerPoint documents are extracted into MD_<name>_<ext>/images/, and the generated Markdown contains relative image links. Conversion continues through a batch if an individual file fails; the process exits with status 1 if any input fails.

Contributing

Contributions are welcome. Please refer to CONTRIBUTING.md for contribution guidelines. For architectural details, processing pipelines, and internal specifications, see TECHNICAL.md.