hammerdown

hammerdown is a cross-platform tool and Python library for converting PDF, Word, Excel, PowerPoint, OpenDocument, CSV, and plain-text documents into clean Markdown. Embedded images, SVG charts, and mathematical formulas are automatically extracted and formatted.

Table of Contents

• Installation
  • Recommended: Python package (pip)
  • Direct Download (Standalone binaries)
  • File Manager Context Menu Integration
• Usage
  • Command Line Interface
  • Logging and Progress Tracking
  • Extracting Base64 Images from Markdown
  • Python Library Quickstart
• Supported Formats
• Output Directory Layout
• Math Formulas and Symbol Normalization
• Documentation links

Installation

Recommended: Python package (pip)

If Python (3.10+) is installed on your system, install via pip:

pip install hammerdown

Or install from local source:

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

File Manager Context Menu Integration

You can integrate hammerdown directly into your OS file manager to convert documents with a single right-click, without opening a terminal:

hammerdown --install

What this does:

• on Windows: adds a Hammer down file action with an icon to the File Explorer context menu for all supported document formats, adds folder context menu options for recursive directory conversions, creates a Send to shortcut (Send to -> Hammer down) for first-level access in Windows 11, and activates an IPC coordinator to process multi-file selections in a single terminal window
• on Linux: installs the launcher into ~/.local/bin, installs a FreeDesktop application entry in ~/.local/share/applications/hammerdown.desktop with MIME associations, registers KDE Dolphin ServiceMenus in ~/.local/share/kio/servicemenus and ~/.local/share/kservices5/ServiceMenus, and adds scripts for Nautilus, Nemo, and Caja (Scripts -> Hammer down file)
• on macOS: installs the launcher into ~/.local/bin, creates an Automator Quick Action in ~/Library/Services/Hammer down.workflow for the Finder right-click context menu, and generates a drag-and-drop Droplet in ~/Applications/Hammer down.app with CFBundleDocumentTypes for Finder "Open With"

To convert a file or folder, right-click any supported document or folder and select Hammer down file (or use Send to -> Hammer down). The Markdown output and extracted images are saved directly next to each original document.

To remove file manager integration and clean up shortcuts:

hammerdown --uninstall

To update hammerdown to the latest version:

hammerdown --update

Usage

Command Line Interface

Convert one or multiple files:

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

Options:

• -i, --in-place -- save output Markdown and extracted images in the same directory as the source file
• -w, --overwrite -- overwrite plain-text source files (.txt, .md, .log, .csv) in-place instead of creating a copy
• -s, --skip-existing -- skip conversion if target Markdown file already exists (overwriting is enabled by default)
• -m, --merge OUTPUT_MD -- merge all converted Markdown documents into a single target Markdown file
• -q, --quiet -- suppress routine status output
• -v, --version -- display version information

hammerdown -i document.pdf
hammerdown -s document.pdf
hammerdown -m summary.md file1.pdf file2.docx
hammerdown folder/

Logging and Progress Tracking

When converting documents from the terminal, hammerdown displays an interactive real-time progress bar indicating the exact progress (e.g., page, slide, or sheet counts):

Processing document.pdf: [████████████░░░░░░░░] 60% (30/50 pages)
Completed document.pdf in 1.4s (3 images extracted)

In non-interactive environments (CI/CD pipelines, redirected log files, or non-TTY outputs), progress is logged as periodic status lines starting from 0% without terminal control characters:

[hammerdown] Processing document.pdf (50 pages, est. ~45s)...
[hammerdown] Processing document.pdf: 0/50 pages (0%)...
[hammerdown] Processing document.pdf: 1/50 pages (2%)...
...
[hammerdown] Processing document.pdf: 50/50 pages (100%)...
[hammerdown] Completed document.pdf in 1.4s (3 images extracted)

When using hammerdown as a Python library, custom progress callbacks can be passed to to_markdown() or convert_file():

def on_progress(current: int, total: int, unit: str):
    print(f"Processed {current}/{total} {unit}")

hammerdown.convert_file("document.pdf", progress_callback=on_progress)

Extracting Base64 Images from Markdown

If you have a Markdown file with embedded base64 images (such as data:image/png;base64,...), running hammerdown with --in-place will extract those raw image strings into PNG or JPEG files inside hm_images_<stem>_<ext>/ and replace inline base64 data URIs with clean relative links:

hammerdown document.md --in-place

Python Library Quickstart

Use hammerdown directly in your Python code:

import hammerdown

# Convert a file on disk
hammerdown.convert_file("document.pdf", skip_existing=True)

# Get Markdown text in memory
text, image_count = hammerdown.to_markdown("report.docx")

For specialized format converters and low-level helpers, see docs/PYTHON.md.

Supported Formats

• PDF and E-books: .pdf, .epub, .mobi, .fb2, .xps
• Word and OpenDocument: .docx, .doc, .odt
• Spreadsheets: .xlsx, .xls, .csv
• Presentations: .pptx, .ppt
• Text and Markdown: .txt, .md, .log

Output Directory Layout

Output Markdown files are saved using the template hm_<stem>_<ext>.md to avoid conflicts when files of different formats share the same base name.

Before conversion:

folder/
└── document.pdf

After conversion:

folder/
├── document.pdf
├── hm_document_pdf.md
└── hm_images_document_pdf/
    └── img_p001_xref105.png

Math Formulas and Symbol Normalization

Equations inside Word and OpenDocument files are automatically translated into standard LaTeX syntax. Special math characters and Greek letters are mapped using a catalog aligned with official LaTeX references:

• Official Reference: Rice University LaTeX Symbols Reference
• Bundled Copy: symbols.pdf

Documentation links

For additional guides and specifications:

• Python API Reference -- complete guide to Python library methods
• Technical Reference -- internal format processing and parser details
• Architecture -- system layers and Mermaid pipeline diagram
• Performance & Estimation Model -- conversion benchmarks, multi-threading architecture, and ETA model
• Contributing Guidelines -- development setup and testing guidelines