v3.2.2

[3.2.2] - 2026-10-29

Fixed

• Windows Context Menu: restored double quotes "%1" in registry commands (resolves issue where files with spaces were split into multiple arguments)
• Packaging: include all assets in src/hammerdown/assets/ in the PyPI wheel and source distribution (fixes missing red/orange icons in context menu)
• Tests: updated integration tests to enforce correct quoting for Windows shell verbs

---

v3.1.0-pre1

[3.1.0-pre1] - 2026-10-23

Note

Prerelease. Release notes were auto-generated only.

Added

• Google Docs/Drive file link support (HTML export via ZIP)
• Google Docs/Drive export download and ignore cache

Full Changelog: v3.0.4...v3.1.0-pre1

v3.0.4

[3.0.4] - 2026-10-11

Note

Release notes were auto-generated only.

Fixed

• Windows: show context verb for mixed selections and allocate one console

Changed

• CI: treat plain tags as stable and suffixed tags as prereleases

Full Changelog: v3.0.3...v3.0.4

v3.0.1

hammerdown 3.0.1

A major release that turns hammerdown from a one-file-at-a-time converter into a proper batch tool with an interactive terminal UI, a merge mode, and a clean stdout pipeline.

Version 2.1.0 was staged in code during development but never released. The CLI overhaul below made it a major bump, so the next published version is 3.0.1.

Breaking changes

• removed -f / --force, --in-place, --in_place, and --quiet
• -i is no longer the in-place shortcut: it is now -i / --include
• long option names accept hyphens only, so --skip_existing is rejected in favor of --skip-existing
• overwriting an existing target Markdown file is the default; use -s / --skip-existing to preserve it
• in_place and DEFAULT_IN_PLACE are gone from the public Python API

New features

Include and exclude filters

-i / --include and -e / --exclude accept repeatable regular expressions matched against each candidate's normalized relative path. Include narrows the recursive scan first, then exclude removes matches, so exclusions always win. Invalid patterns abort the run before any conversion starts.

Merge mode

-m / --merge OUTPUT_MD converts many documents and concatenates them into a single Markdown file. The output opens with a Directory structure: tree of the sources relative to their common root, then one block per document introduced by a line of 48 = characters, a line such as FILE: notes/draft.md, and the same separator again.

Extracted assets are namespaced next to the merge target: a target named summary.md uses hm_merged_into_summary_images/, mirroring each document's relative path, and image links are rewritten to match. The file is appended as the batch runs, so an interrupted run still leaves a usable partial document.

Streaming to stdout

--stdout emits the same merged document to stdout without writing any intermediate hm_*.md files. Each conversion runs against a temporary output directory and every asset is inlined as a base64 data URI, so the stream is self-contained. Diagnostics and errors go to stderr, and the exit code is non-zero when any document failed.

--confirm adds a preflight that reports the file count, a token estimate for plain-text sources, and an estimated duration, then asks [y/n]. y and yes proceed, n and no cancel, and any other answer re-asks. Without an interactive stdin it cancels safely instead of waiting.

Interactive batch UI

Batch runs in a TTY now render a live Rich view with a Summary panel (elapsed time, estimate, completed count, token totals, error count) and a Processing panel showing a sliding window of the file queue. Completed files show a green marker, the active file shows a progress bar with live elapsed time, queued files show their preflight estimate, and failures show a red marker. The Processing panel border uses the running color #ec7c39 while active and the completion color #729c1f once finished.

Errors are reported in a separate Error list panel and never counted in Results.

Single-process Explorer launch

On Windows, multi-file selections in Explorer no longer spawn one process per file. Explorer's native multi-select grouping (MultiSelectModel = "Player" plus an Advanced Query Syntax AppliesTo filter) passes supported files to one process, and a local IPC coordinator (\\.\pipe\hammerdown_coordinator) catches additional launches, assembling incoming paths over a 0.35-second window before rendering them together.

Other additions

• rich is now a runtime dependency for the terminal UI
• tiktoken encoding data is bundled into standalone builds so token counts work offline
• a folder-or-file mode prompt for batch selection, with modern folder picking

Fixes

• keyboard interrupts now exit cleanly instead of leaving a broken terminal state
• path deduplication and recursive folder expansion were corrected for mixed file and directory arguments
• the terminal no longer needs an extra keypress after a batch conversion
• PDF page chunking was tuned, and a regression that hurt performance was reverted
• legacy Office conversion diagnostics now report which converter was tried and why it failed
• Rich live rendering was stabilized: fixed panel size, no duplicate final frames, no transient progress bars
• the stdout temporary output directory is guarded against premature cleanup
• the --confirm preflight now sums the estimates it has instead of reporting unknown as soon as one file lacks one, and its token count covers only plain-text sources so compressed PDF, DOCX, and XLSX payloads no longer inflate the number
• batch summaries and error output were refined so counts and reasons match what actually happened

Internal hardening (this release)

• the oversized batch.py, core.py, and batch_ui.py modules were split into focused modules: discovery, estimates, resources, stdout_mode, batch_ui_render, and platform_utils. No source file exceeds roughly 400 lines
• the Markdown table renderer and the math-glue predicate are now shared across the OpenDocument, Word, PowerPoint, and spreadsheet parsers, which also fixed unescaped pipes inside PowerPoint table cells
• the integrations package gained a shared _common module for launcher, quoting, and cleanup helpers, and platform checks go through platform_utils
• --update now compares versions numerically, verifies the downloaded binary by SHA-256 (with the GitHub asset digest and byte size as fallbacks), checks the executable magic bytes, and stages the new binary with a swap plus rollback
• IPC connections are closed in finally blocks, the coordinator survives a failed connection, and incoming file payloads are validated
• the Windows file picker returns on cancel instead of opening a second dialog
• the PDF converter no longer writes image files that nothing references, and its progress counter is lock-guarded across worker threads

Documentation

• README.md documents the merge and stdout pipelines in full, moves the supported-format list directly under the project description, illustrates the live batch view with cropped screenshots, and credits gitingest for the -m, -i, and -e flag functionality
• PyMuPDF and PyMuPDF4LLM are now explicitly named as the core the PDF pipeline is built on
• docs/ARCHITECTURE.md gained a module layout map, the merge and stdout pipelines, the traversal pruning rules, and an accurate description of the interactive progress UI
• docs/TECHNICAL.md had its naming rules, PDF section, merge section, and performance list corrected
• docs/PERFORMANCE.md now matches the estimation formulas in estimates.py and no longer claims multi-process batch conversion
• docs/PYTHON.md documents the real convert_file signature, the ConversionResult dataclass, the convert_files batch API, and the corrected to_markdown parameter name
• CONTRIBUTING.md builds from hammerdown.spec, documents HAMMERDOWN_EXECUTABLE, and adds a pyright verification step

Verification

• python -m pytest -q -- 104 passed
• python -m pyright -- 0 errors, 0 warnings

Full Changelog: v2.0.4...v3.0.1

v2.0.4

What’s Changed in v2.0.4

Hammerdown 2.0.4 focuses on UX refinements for batch operations, accurate conversion duration estimations across all 16 supported document formats, clean terminal progress rendering, and completely invisible child window delegation on Windows.

New Features & UX Improvements

• Complete Format Estimations (16 Supported Formats):
  • PDF & E-books (.pdf, .epub, .mobi, .fb2, .xps): Exact page count heuristics (X pages, est. ~Ys).
  • Word Documents (.docx): Fast ZIP metadata peeking (docProps/app.xml or compressed word/document.xml size fallback).
  • PowerPoint Presentations (.pptx): Fast ZIP XML slide counting (X slides, est. ~Ys).
  • Excel Spreadsheets (.xlsx): Fast ZIP XML sheet counting (X sheets, est. ~Ys).
  • OpenDocument Text (.odt): Compressed content.xml size estimation.
  • Legacy Formats (.doc, .xls, .ppt): File-size based duration heuristics (legacy format, est. ~Ys).
  • Plain Text & CSV (.txt, .md, .log, .csv): Instant text processing indicator (fast text conversion).
• Clean & Ordered Terminal Batch Output:
  • Sequential execution in TTY batch mode prevents interleaved log lines and mangled progress bars caused by multi-process output race conditions.
  • Deterministic file sorting prior to processing guarantees predictable batch conversion order.
  • Silent Delegate Windows on Windows:
  • Child delegate processes spawned via context menu selections instantly hide their console window (SW_HIDE) prior to IPC election,
  • preventing transient terminal popups when converting multiple files.Reliability & Fixes
• CI/CD Pipeline & Package Release Sync:
  • Full alignment across PyPI release artifacts, standalone PyInstaller executables, and GitHub Release assets under protected version tags.

Full Changelog: v2.0.1...v2.0.4

v2.0.0

What's Changed in v2.0.0

Hammerdown 2.0.0 is a major release introducing expanded cross-platform file manager integration, streamlined output conventions, single-instance coordination on Windows, directory recursion, and document merging.

Breaking Changes

• Overwriting is now enabled by default: converting a file overwrites existing target Markdown output unless explicitly skipped.
• Removed --force (-f) flag: replaced by the -s / --skip-existing flag to prevent overwriting existing files when desired.
• Output naming standard: Markdown output files now consistently follow the hm_<stem>_<ext>.md naming pattern, and extracted images are saved into hm_images_<stem>_<ext>/ directories.

New Features & Highlights

• Windows File Explorer Integration:
  • Added folder context menu entries to convert entire folders recursively.
  • Added a Send to shortcut (Send to -> Hammer down) for fast access in Windows 11.
  • Single-Instance IPC Coordinator: selecting multiple files and converting them runs in a single console window rather than spawning dozens of windows.
• Linux File Manager Integration:
  • FreeDesktop .desktop application entry (~/.local/share/applications/hammerdown.desktop) with MIME type associations for all supported document formats.
  • KDE Dolphin ServiceMenus for KDE Plasma 5 and KDE Plasma 6 (~/.local/share/kio/servicemenus).
  • Context menu scripts for GNOME Nautilus, Nemo, and Caja (Scripts -> Hammer down file).
• macOS Finder Integration:
  • Native Automator Quick Action (~/Library/Services/Hammer down.workflow) available directly in the Finder right-click context menu.
  • Droplet application (~/Applications/Hammer down.app) supporting drag-and-drop file processing and Finder "Open With" associations.
• Recursive Directory Traversal:
  • Passing a directory path automatically scans and converts all supported documents in its tree while ignoring temporary lock files (~$*) and hidden files (.*).
• Document Merging (-m / --merge):
  • Allows concatenating multiple converted documents into a single consolidated Markdown file with document headers.
• Branding & Assets:
  • High-resolution squircle icon packaged natively across platforms with clean #0e1117 background corners.

Performance & Reliability

• Lazy loading for all heavy document parser dependencies (pymupdf, python-docx, openpyxl, python-pptx).
• Multi-threaded background disk I/O for image extraction.
• Fully tested across Windows, Linux, and macOS matrix environments.

Full Changelog: v1.5.1...v2.0.0

v1.5.2

hammerdown v1.5.2

Bug Fixes

• CLI Update Integration: hammerdown --update now enforces --no-cache-dir during pip upgrades and automatically re-runs integration installation (install()) so Windows Explorer context menus and runner scripts are updated instantly.
• Native MS Office Integration via PowerShell (Windows): Legacy binary formats (.doc, .xls, .ppt) now attempt conversion using installed Microsoft Office applications (Word, Excel, PowerPoint) via system PowerShell COM automation first. This works out-of-the-box on Windows without requiring any extra Python dependencies (win32com has been completely removed).
• Robust LibreOffice Cascade: Improved cross-platform discovery for LibreOffice (soffice), including standard search paths on Windows (Program Files), macOS (/Applications/LibreOffice.app), and Linux (PATH).
• Safe Legacy ZIP Handling: Wrapped file container checks in try...except so non-standard or corrupt legacy office files gracefully fall back to external converters instead of raising unhandled exceptions.
• Streamlined CLI & Updates: Cleaned up the installation success message (removed the obsolete file manager restart prompt). hammerdown --update now enforces --no-cache-dir during pip upgrades and automatically re-runs install() so runner scripts and Windows context menu integrations update instantly.

Tests

• Added test coverage for legacy .doc files with Cyrillic filenames and non-standard OpenXML structures.
• Optimized golden test suite with concurrent thread-pool conversion execution.

Full Changelog: v1.5.1...v1.5.2

v1.5.1

Release Notes

Bug Fixes & UI Enhancements

• Square context menu icon: removed rounded corners (rx="112") from assets/logo.svg and regenerated icon.ico so the icon displays as a clean square matching Windows File Explorer dark theme context menu styling without black circular background artifacts.

Version Bump

• Updated package version to v1.5.1.

Full Changelog: v1.5.0...v1.5.1

v1.5.0

Release Notes

Features & Improvements

• In-place text source overwrite (-w / --overwrite): added CLI option allowing plain-text formats (.txt, .md, .log, .csv) to overwrite the source file directly without generating intermediate copy filenames.
• Binary source protection: binary files (.pdf, .docx, .xlsx, .pptx, .odt, .doc) strictly ignore --overwrite to prevent accidental loss of original documents.
• Detailed progress logging: non-TTY progress logging now starts at 0% and logs every integer percentage step for granular tracking of large document conversions.

Documentation & Tests

• Updated CLI help, README.md, docs/PYTHON.md, docs/TECHNICAL.md, and docs/ARCHITECTURE.md.
• Added unit tests covering -w / --overwrite for plain-text and binary formats as well as 0% progress logging.

Full Changelog: v1.4.0...v1.5.0

v1.4.0

v1.4.0 - Real-time Progress Tracking & GFM LaTeX Math Fixes

What's Changed:

• Real-time Progress Tracking: added an interactive progress bar in the terminal displaying progress by pages, slides, sheets, or document elements.
• Clean Non-TTY / CI Logging: in non-interactive environments (scripts, log files, CI/CD), progress is logged periodically with milestone entries (~25% intervals) without control characters.
• Python API Progress Callback: added progress_callback(current, total, unit) parameter to to_markdown(), convert_file(), and all format converters.
• GFM Math Rendering Fix: escaped inline math underscores (_ -> _) in Word (.docx, .doc) and OpenDocument (.odt) converters to prevent GitHub Markdown from parsing inline math subscripts into HTML ... tags.
• Documentation: updated README.md and docs/PYTHON.md with logging, progress tracking, and API usage details.

Full Changelog: v1.3.2...v1.4.0