Skip to content

README.md

Latest commit

 

History

History
117 lines (89 loc) · 6.51 KB

README.md

File metadata and controls

117 lines (89 loc) · 6.51 KB
Raw

Double Commander Plugins for macOS

Native plugins for Double Commander on macOS, built to a consistent engineering standard: universal binaries (Apple Silicon + Intel), headless tests, CI, and a layered safety gate before anything ships.

So far that means a Markdown preview/viewer plugin for Double Commander (renders .md files in the F3 viewer, with a toggle back to raw text), a media-info plugin that shows image and video resolution, duration, and PDF page count as custom columns, and an e-book reader that opens EPUB and FictionBook files in the viewer with a contents sidebar — the things people reach for as a "Double Commander Markdown plugin", an "image dimensions column on macOS", or an "EPUB / FB2 viewer plugin for Double Commander" (of which there was no macOS one at all). All are WLX/WDX plugins using the Total Commander plugin ABI.

This repo is also a worked example of how I build small native tools end-to-end — investigate the platform, prove the mechanism with a focused test before writing the feature, fix root causes instead of papering over them, and keep the result reproducible and documented.

Plugins

Plugin Type What it does Status
markdown-wlx WLX (lister) Renders Markdown beautifully in DC's viewer (F3) — GitHub-style CSS, syntax highlighting, tables, task lists, Mermaid diagrams, KaTeX math, configurable light/dark. Toggle back to raw text anytime. ✅ stable
media-info-wdx WDX (content) Shows media metadata in custom columns & tooltips — image/video resolution, audio/video duration, bitrate, codecs, PDF page count, plus an adaptive Summary field. Native ImageIO / AVFoundation / CGPDF; no deps, no network. ✅ stable
book-wlx WLX (lister) Reads EPUB and FictionBook (FB2) e-books in the viewer (F3) — contents sidebar, continuous reflowable text, cover, reading progress, adjustable text size, light/dark/sepia. Served straight out of the container in-process: nothing unpacked to disk, nothing fetched from the network. ✅ stable

More plugins will follow; the repo layout and the contributor guide are built for that.

What the viewers look like

A Markdown file rendered in Double Commander's viewer by MarkdownView — with KaTeX math, a Mermaid diagram, syntax-highlighted code, and tables

Press F3 on any .md file and it opens rendered. The built-in viewer's mode switch still lets you flip to the raw Text view (and back) at any time.

An EPUB open in Double Commander's viewer with BookView — contents sidebar with the current chapter highlighted, chapter text set as a book, a plate with its caption, and a table

F3 on an .epub, .fb2 or .fbz opens the book itself — contents sidebar, continuous reflowable text, cover and reading progress — instead of the container.

Quick start

Requires macOS 11+ and the Xcode command-line tools (xcode-select --install). Every plugin builds and installs the same way:

cd book-wlx        # or markdown-wlx, or media-info-wdx
./build.sh         # → build/<Plugin>.wlx|wdx  (universal: arm64 + x86_64)
# Quit Double Commander first (it rewrites its config on exit), then:
./install.sh       # installs to ~/Library/Preferences/doublecmd/ and registers it

Prebuilt bundles that need no Xcode are on the releases page: unzip, quit Double Commander, run ./install.sh.

Per-plugin details — supported extensions, how it works, uninstall — live in each plugin's own README (e.g. book-wlx/README.md).

What a "plugin" is here

A Double Commander plugin is a native shared library with a fixed C entry-point table (the Total Commander plugin ABI). A WLX lister plugin like markdown-wlx or book-wlx is a .wlx Mach-O dylib exporting ListLoad, ListLoadNext, ListCloseWindow, ListGetDetectString, and ListSetDefaultParams. On macOS the window handles in that ABI are NSView*, so a viewer plugin builds an NSView (here, a WKWebView) and hands it back to DC. A WDX content plugin like media-info-wdx is a .wdx dylib exporting ContentGetSupportedField / ContentGetValue instead — it returns data fields DC renders in custom columns and tooltips rather than a view.

The deeper design — the ABI, the rendering pipeline, and a couple of instructive macOS gotchas (e.g. why WKWebView swallows the Escape key, and the fix) — is in the project wiki and summarized in docs/ARCHITECTURE.md.

Engineering standards

Every plugin in this collection aims to hold the same bar:

  • Native & universal — one .wlx runs on Apple Silicon and Intel (lipo verified).
  • Tested — a headless harness loads the real built plugin and asserts behavior (it renders; Escape reaches the host). GUI-bound tests run locally; CI verifies the build, architectures, and exported ABI symbols.
  • Reproducible — third-party assets are vendored and attributed; the build is a single script with no hidden state.
  • Safe to publish — a generic leak-guard gate (secrets, private paths, OS cruft) runs in CI and as a pre-commit hook.
  • Root-cause fixes — bugs are understood before they're patched; see the Escape-key case study in the wiki.

Repository layout

.
├── markdown-wlx/            # Markdown lister plugin (WLX): renders .md in the viewer
├── book-wlx/                # e-book lister plugin (WLX): reads EPUB and FB2 books
├── media-info-wdx/          # media-metadata content plugin (WDX): dimensions, duration, …
├── docs/                    # cross-plugin docs (architecture, adding a plugin)
├── scripts/leak-guard.sh    # generic pre-publish safety gate
├── .github/                 # issue/PR templates, CI workflow
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE                  # MIT

Contributing

See CONTRIBUTING.md for the build/test loop, the plugin layout convention, and docs/ADDING-A-PLUGIN.md for scaffolding a new one. Issues and proposals are welcome via the templates.

License

MIT © Nikolai Sachok. Bundled third-party libraries keep their own licenses — see each plugin's THIRD_PARTY_LICENSES.md.