Introduction

In the DeepSeek Harness (DSH) plugin ecosystem, converting Office documents or PDFs to Markdown is a frequent requirement. Existing solutions present privacy risks when using external services, while local conversion often struggles to balance layout preservation with scanned document recognition. The dsh-md-convert plugin is based on Microsoft’s MarkItDown engine and provides a locally running solution that supports multiple conversion pipelines, including OCR.

Plugin Overview

This plugin is maintained by user yakoylp and is licensed under MIT. It aims to convert Office documents (.doc/.docx/.xls/.xlsx/.ppt/.pptx) and PDFs (including text layers and scanned documents) into Markdown while preserving structural-level layout. The plugin offers two usage modes: CLI commands and the DSH Agent tool.

Core Features

The core conversion logic automatically routes based on the input format:
1. Direct conversion for modern formats: .docx, .xlsx, .pptx, and PDF text layers are processed directly by the MarkItDown engine, preserving heading levels, lists, tables, and paragraph order.
2. Legacy format conversion: .doc, .xls, and .ppt files must first be saved into new formats through a backend (WPS/Office or LibreOffice) before being converted to Markdown. The plugin can automatically detect the backend, or you can specify it manually.
3. OCR for scanned documents: For PDF scans without a text layer, the plugin uses a lightweight CPU model routing pipeline for recognition. The routing process includes PP-DocLayout-L layout analysis, RapidOCR text recognition, SLANet table structure extraction, and FormulaNet formula recognition.

Installation and Activation

Install the plugin in a DSH environment:

dsh plugin --profile web add github:yakoylp/dsh-md-convert

After installation, restart the dsh web service. Then the Agent can use the md_convert tool, and the CLI command dsh-md-convert will also be available in node_modules/.bin of the profile.

Command-Line Usage

The plugin provides the dsh-md-convert command, supporting batch processing and dependency checks.

  1. Batch conversion
dsh-md-convert a.docx b.pdf -o ./md
  1. Process legacy formats
dsh-md-convert old.doc old.xls old.ppt -o ./md
  1. Force a legacy format backend
dsh-md-convert old.doc -o ./md --legacy-backend wps
  1. Process scanned documents
dsh-md-convert scan.pdf -o ./md
  1. Check dependencies and models
dsh-md-convert deps

On the first scanned-document conversion, the plugin automatically downloads OCR models to ~/.paddlex/, after which it can be used fully offline.

Agent Tool Usage

After installing the plugin, the Agent can directly invoke the md_convert tool:

md_convert({ file: "报告.docx", outDir: "./md" })

The plugin configuration file cordis.patch.yml defines the tool behavior, including parameters such as output directory, whether to force OCR, OCR scaling ratio, and backend selection.

Notes

  1. Environment dependencies: When running on a headless Linux server, it is recommended to install the Chinese font fonts-noto-cjk. Legacy format conversion on Windows requires WPS or Office to be installed locally; Linux/macOS require LibreOffice.
  2. Automatic dependency installation: Dependency auto-installation is enabled by default. On the first scanned-document conversion, dependencies such as paddlepaddle and paddleocr are installed automatically. If manual control is needed, use --no-auto-install-deps.
  3. PaddlePaddle version: PaddlePaddle 3.3 and later versions require disabling oneDNN to avoid crashes. The plugin handles this issue automatically.
  4. Error codes: The CLI and Agent return stable error codes (0/1/2), allowing callers to determine the conversion result.
  5. Limitations: Because Markdown itself cannot express font/font size/color, these visual details are lost during conversion. In addition, complex layouts or extremely small fonts may result in incomplete recognition.

Summary

The dsh-md-convert plugin uses the MarkItDown engine and local OCR routing to provide DSH with a lightweight, offline-capable capability for converting documents to Markdown. It is suitable for scenarios that involve processing large volumes of documents while emphasizing privacy and structure preservation.

  • Official directory: https://www.skillhub.cn/plugins/yakoylp/dsh-md-convert
  • Source code: https://github.com/yakoylp/dsh-md-convert