dsh-markdownize

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

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)

1. Attach a compatible file to the composer, or mention one with @.
2. 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.