dsh-markitdown

dsh-markitdown

Microsoft MarkItDown as a DeepSeek Harness tool. One tool, markitdown, turns a document into Markdown the model can actually read.

The model calls it before reading any non-text file:

markitdown({ input: "reports/q3.pdf" })
markitdown({ input: "data/forecast.xlsx", output: "notes/forecast.md" })
markitdown({ input: "https://example.com/spec.html" })

Why this exists

A text-only model cannot open a PDF, a spreadsheet, or a slide deck. MarkItDown solves that well — but it is a Python package, and a harness plugin needs to reach it without assuming a specific Python environment, a specific install layout, or that anything is installed at all.

So this plugin does not reimplement MarkItDown and does not vendor it. It looks for a real installation, drives it, and falls back to a built-in converter when there is none:

Order	Engine	What it is	Needs
1	markitdown	Microsoft's own CLI	pip install "markitdown[all]"
2	uvx markitdown	the real package, run without installing it	uv
3	python -m markitdown	a Python that already has the package	Python 3.10+ with MarkItDown
4	built-in	a dependency-free converter shipped in this plugin	nothing

Order 2 is usually the best deal: if uv is on the machine, the real MarkItDown runs with no permanent install. It defaults to the markitdown[all] spec so Office and PDF formats actually work — plain markitdown has no format converters at all.

Order 4 keeps the tool useful on a bare machine. It is honest about its limits rather than guessing.

Fidelity

Format	Real MarkItDown	Built-in fallback
PDF	full layout extraction	not supported — says so, names the fix
Word .docx	full	headings, paragraphs, lists, tables
Excel .xlsx	full	sheets, shared strings, numbers, tables
PowerPoint .pptx	full	slide-by-slide text
HTML / .epub	full	headings, lists, links, tables, code
CSV / TSV / JSON / XML	full	tables / fenced JSON / flattened text
Jupyter .ipynb	full	markdown and code cells
Images, audio, YouTube	OCR and transcription	not supported
Plain text and code	passthrough	passthrough

The built-in converter is a safety net, not a replacement. When it is used, the result says so and names the command that unlocks full fidelity.

Install

Requirements

DeepSeek Harness 0.1.5-rc.1 or newer on either release line — 0.1.x and 0.2.x are both supported:

"engines": { "dsh": ">=0.1.5-rc.1 <0.3.0-0" }

Verified against harness 0.1.5-rc.2, 0.2.0-rc.2, 0.2.1-rc.5, and 0.2.2-alpha.2: the build, the type check, and the test suite pass on each, and on 0.2.1-rc.5 the plugin was also mounted from a real profile, where the markitdown tool registered and converted a file. The 0.2 line raised the harness's own schemastery dependency to ~3.18.4 (0.2.1: ~3.18.5) and cordis to ~4.0.4 (0.2.1: ~4.0.5); neither affected this plugin, which only binds tools.register and the schemastery DSL — its compiled output is identical across these versions.

The range deliberately admits prereleases: DSH compares engines.dsh with prerelease semantics, so each 0.2.x prerelease is covered without pinning it.

Node ^22.19.0 || >=24.0.0.

Every install below goes through dsh plugin, which runs pnpm, so make sure pnpm is on your PATH (npm install -g pnpm).

From GitHub

dsh plugin --profile web add github:jiekesu967/dsh-markitdown

The compiled lib/ is committed, so this path needs no build step.

From a release tarball

Download dsh-markitdown-<version>.tgz from Releases, then:

dsh plugin --profile web add ./dsh-markitdown-<version>.tgz

From npm

dsh plugin --profile web add dsh-markitdown

The package is published from this repository: https://www.npmjs.com/package/dsh-markitdown.

Then restart dsh web. The markitdown tool appears in the next session.

Nothing else is required. For PDF, OCR, audio, and full-fidelity Office conversion, install one of:

pip install "markitdown[all]"     # or
winget install astral-sh.uv       # Windows: then `uvx markitdown` works with no install
curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS

Configuration

Every field is optional; defaults are shown.

- id: markitdown
  name: dsh-markitdown
  config:
    engine: auto              # auto | markitdown | uvx | python | builtin
    uvxPackage: "markitdown[all]"   # slim it to "markitdown[pdf,docx,pptx,xlsx]"
    command: ""               # explicit markitdown executable, overrides PATH
    env: {}                   # extra environment variables for the external engine
    timeoutMs: 120000         # per-conversion deadline
    maxChars: 120000          # inline result cap; longer output is truncated
    maxBytes: 67108864        # bytes the built-in engine will read
    allowUrls: true           # accept http(s) inputs
    extraArgs: []             # extra CLI arguments for the external engine

engine: auto probes the chain once per plugin instance and caches the winner. Setting an engine explicitly disables the fallback: if you ask for uvx and there is no uv, the call fails with the reason and the fix, rather than quietly converting with something else.

A first uvx run downloads MarkItDown and its dependencies (about a minute). Package-manager progress lines are filtered out of the tool result; only real diagnostics are reported.

env is a map of extra environment variables handed to the external engine's conversion process — the CLI, uvx, and python engines alike. It is layered over the UTF-8 settings the plugin already passes (PYTHONUTF8=1, PYTHONIOENCODING=utf-8), and your value wins per key. It exists so a locale that still corrupts output can be fixed in configuration instead of by patching files under node_modules, and it is also how to hand MarkItDown a proxy or SSL_CERT_FILE without changing the environment of the whole harness.

Behaviour worth knowing

• Relative paths resolve against the session workspace, exactly like the built-in file tools, not the harness process working directory.
• output writes through the filesystem seam, so the per-session sandbox policy and the read-before-write observation rule both apply. Writing to an existing file re-reads it first.
• A missing input fails before any subprocess starts, with one clear sentence instead of an engine traceback.
• Truncation is announced. If the Markdown exceeds maxChars and no output path was given, the result says it was truncated and how to get the rest.
• Subprocesses are launched with shell: false. A filename or URL containing shell metacharacters is one argv element and can never become a command. Only real executables are accepted; .cmd/.bat shims are rejected because running them would require a shell.
• MarkItDown performs I/O with the privileges of the current process. Treat untrusted input accordingly, and see MarkItDown's own security guidance.

Resource limits

Converting untrusted documents means the input decides how much work the converter does, so every cap is enforced while reading rather than after:

• Local files are refused above maxBytes, both through the filesystem seam and on the fallback path that runs without it. The size comes from stat first, so a small file never reserves the whole cap.
• URL responses are bounded during transfer: a declared content-length over the cap is refused without downloading anything, and a streamed body is cancelled mid-transfer once it passes the cap.
• Archive entries carry a decompression limit, so a few-kilobyte ZIP cannot expand into gigabytes. The default is 256 MiB per entry, overridable with unzip(buffer, maxEntryBytes) and convertBuiltin(bytes, name, { maxEntryBytes }).
• Spreadsheet cell references beyond Excel's own last column (XFD) are dropped rather than used to size a row array.
• Subprocess output is capped, and a child terminated for exceeding it says so — instead of being reported as a timeout, which named the wrong cause and the wrong fix.

Development

npm run build      # compile src/ → lib/
npm test           # built-in converter + plugin surface tests
npm run typecheck  # type check only

The build links the DSH packages from $DSH_CHECKOUT (a source checkout) or $DSH_RUNTIME (an installed runtime). With neither set it finds the runtime itself — the dsh on your PATH, this Node installation's global prefix, or npm root -g — so plain npm run build works with no setup. It then compiles with the TypeScript compiler API in a single Node process — no shell, so it also runs on Windows. Rebuilding an unchanged tree leaves lib/ byte-identical.

Tests need no network, no Python, and no MarkItDown install: the fallback engine is exercised against synthetic OOXML fixtures built in-process. If your environment forbids spawning child processes, npm run test:inline runs them all in one.

src/index.ts     plugin wiring: config, tool definition, execute path
src/engine.ts    engine chain: probe, cache, launch
src/builtin.ts   dependency-free converters
src/text.ts      entity decoding, HTML→Markdown, delimited parsing
src/zip.ts       minimal ZIP reader for OOXML/EPUB containers
src/exec.ts      subprocess plumbing with honest failure reporting

Credits

MarkItDown is Microsoft's work, MIT licensed: https://github.com/microsoft/markitdown. This plugin only drives it. Trademarks belong to their owners; this project is not affiliated with or endorsed by Microsoft.

License

MIT — see LICENSE.