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
• Usage
  • Command Line Interface
  • 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

Register system context menu integration using --install:

hammerdown --install

To remove integration:

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
• -f, --force -- overwrite existing output Markdown files
• -q, --quiet -- suppress routine status output
• -v, --version -- display version information

hammerdown -i document.pdf
hammerdown -f report.docx

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
• Contributing Guidelines -- development setup and testing guidelines