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 (no administrator privileges required)
• on Linux: installs the executable into ~/.local/bin and adds a context script for GNOME Nautilus (Scripts -> Hammer down file)

To convert a file, right-click any supported document (.pdf, .docx, etc.) and select Hammer down file. The Markdown output and extracted images are saved directly next to the 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
• -f, --force -- overwrite existing output Markdown files
• -q, --quiet -- suppress routine status output
• -v, --version -- display version information

hammerdown -i document.pdf
hammerdown -w notes.txt
hammerdown -f report.docx

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 hammerdown_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", force=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 <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
├── document_pdf.md
└── hammerdown_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
• Conversion Benchmarks & Estimations -- empirical performance tables and ETA model
• Contributing Guidelines -- development setup and testing guidelines