dsh-markdownize
A DeepSeek Harness (dsh) plugin that converts documents to Markdown so an LLM
can read them.
Models work best with plain text. A PDF, a Word file or a spreadsheet read as
raw bytes is noise to them. Markdown keeps the structure (headings, lists,
tables, slides, pages) while staying compact and easy to read. This plugin
gives the agent a convert_to_markdown tool that does that conversion
locally. You can also preview a conversion yourself before anything is sent
to the model.
What it does
convert_to_markdown tool. The model calls it with a local file path
and gets the document back as Markdown, truncated to max_chars
(100,000 by default).- Two conversion engines. You pick one on the plugin's page:
- its own engine, a pure-JavaScript port of MarkItDown's offline
converters, bundled with the plugin and always available;
- Microsoft MarkItDown (Python), used when it is installed.
- Images in DOCX and PPTX. Embedded images become
[Image N: alt text]
markers. When the current model accepts images, each image is sent right
after its marker.
- Debug mode. Preview the Markdown a file turns into from the web
composer (Ctrl+Shift+M). Nothing is sent to the model.
Supported formats
| Format | Own engine (JS) | Microsoft MarkItDown |
|---|
| PDF | yes (text per page) | yes |
Word .docx | yes | yes |
PowerPoint .pptx | yes (text and notes per slide) | yes |
Excel .xlsx | yes (one table per sheet) | yes |
| HTML / HTM | yes | yes |
| CSV / TSV | yes (as a table) | yes |
| JSON / XML | yes (fenced code block) | yes |
| TXT / MD | yes (as is) | yes |
| ZIP | yes (each supported file inside) | yes |
Excel 97 .xls, EPUB, Jupyter .ipynb, Outlook .msg | no | yes |
Conversion engines
Own engine (JavaScript)
convert.js mirrors MarkItDown's offline converters with Node libraries:
mammoth for DOCX;exceljs for XLSX;unpdf (pdf.js) for PDF;turndown with GFM tables for HTML;jszip and fast-xml-parser for PPTX and ZIP.
It needs no Python, no network and no child processes. The libraries ship
pre-bundled in vendor/, so the plugin has no runtime npm dependencies. This
matters because dsh installs local plugins as link: dependencies, and pnpm
never installs a linked package's dependencies.
Microsoft MarkItDown
MarkItDown is Microsoft's Python
tool for the same job. It gives the reference output and reads a few more
formats. Install it with:
pip install "markitdown[all]"
The plugin looks for it on PATH as markitdown, py -m markitdown,
python -m markitdown or python3 -m markitdown. If it lives somewhere else,
such as a virtualenv's markitdown.exe, set its command on the plugin's page.
Use double quotes around paths with spaces.
Choosing the engine
Open Plugins → dsh-markdownize. The page shows which engines were found.
When both are available, choose:
- Automatic (the default): MarkItDown when it is found, otherwise the
JavaScript engine.
- Always MarkItDown: conversions fail if it is missing.
- Always JavaScript.
The choice and the custom command are saved in
<dshHome>/storages/dsh-markdownize/settings.json, together with the image
settings. They apply to both the tool and debug mode. MarkItDown is detected once per Host start; press
Search again after installing it.
Images in documents
The JavaScript engine extracts the images embedded in DOCX and PPTX files
(including those inside a ZIP). Each one leaves a marker where it sat: in the
text for DOCX, after the slide's text for PPTX.
[Image 1: Sales by quarter]
[Image 2]
[Image 3: Company logo — same as image 1]
[Image 4: Vector logo — format not supported]
The plugin's page sets what happens next:
- Send them to the model when it accepts images (the default). The tool
checks the current model's declared input modalities, as the harness's
read_image does. With an image-capable model, each image is stored as an
attachment and sent right after its marker. With a text-only model, such as
DeepSeek's, only the markers are sent, followed by a note saying why.
- Text markers only. Images are never sent.
Most images per conversion (1–50, 10 by default) caps what one call sends,
and never exceeds the harness's own per-message image limit. Images past the
cap keep their marker with a note. The model can also pass
include_images: false to get the markers only; it cannot override the
settings.
Repeated images (a logo on every slide) are sent once. Icons smaller than
32 px on both sides are skipped when they have no alt text. PNG, JPEG, GIF
and WebP are sent; EMF, WMF and TIFF keep a marker only. Debug mode always
shows markers.
MarkItDown does not extract images, so these settings have no effect while
it is the engine in use.
Install
The plugin needs no build step and no Python. For a web profile:
dsh plugin --profile web add ./dsh-markdownize
dsh --profile web --dump-config
The dump should show a # == dsh-markdownize layer. Then start the client:
dsh web
On the desktop profile, add it from the app's plugin manager as a local
folder.
Debug mode (web client)
- Attach a compatible file to the composer, or mention one with
@.
- Press Ctrl+Shift+M.
Each compatible attachment and @file reference is converted on the Host.
@file paths are resolved against the Session's workspace. The full output,
with no truncation, is written to <os tmpdir>/dsh-markdownize-debug/ and
opened in the right Sidebar preview. A composer notice reports its size, path
and the engine used.
Nothing is sent to the model, and the draft is left as it was. Images and
unsupported formats are skipped.
Limits and safety
- Only local files: URLs are rejected (use the web tools for those).
- Files are read with the privileges of the dsh process.
- Files are capped at 50 MB.
- ZIPs are capped at 200 entries and 50 MB uncompressed, and nest at most one
level deep.
- Tool output is truncated at 100,000 characters by default.
Not covered: OCR of scanned documents, images in PDFs, image captioning
for text-only models, audio transcription, YouTube, Azure Document
Intelligence, and the legacy .doc and .ppt formats.
Structure
index.js — the Host half. It registers the convert_to_markdown tool and
the markdownize service (convert, convertPath, status, configure,
configureImages, redetect), served through the Gateway's SRC fallback.engine.js — engine selection, MarkItDown detection and invocation, and
the saved settings.convert.js — the JavaScript engine.images.js — embedded images: markers, model hand-off, and the tool's
output schema.client.js — the Client half: the engine page under Plugins, the
debug-mode shortcut, and the en / es / zh UI strings.locale/ — the plugin's localized title and description.cordis.patch.yml — inserts the dsh-markdownize plugin row.vendor/ — the bundled converter libraries (generated; committed).build-vendor.mjs — rebuilds vendor/.
Rebuilding vendor/
After changing a converter's version in devDependencies:
npm install && npm run build
Commit the regenerated vendor/ files: the plugin loads them at runtime.
License
Copyright 2026 gorkaseto. Licensed under the
Apache License, Version 2.0; see NOTICE for the bundled
third-party libraries and their licenses.
