Introduction¶
When processing documents in DSH, input isn’t always clean Markdown: HTML snippets, email bodies, exported files, and tables that need cleaning all show up. Without dedicated tools, models can only patch together conversion logic in prompts, which often leads to inconsistent HTML entity handling, unstable table structures, and web noise leaking in.
Below we introduce omdsh-dev/dsh-tool-markdown. It targets document processing scenarios such as HTML-to-Markdown conversion, GFM table normalization, and table of contents generation, registering as a markdown tool plugin for DSH.
Plugin Positioning¶
omdsh-dev/dsh-tool-markdown is a DSH Markdown tool plugin maintained by omdsh-dev, licensed under MIT.
Its capabilities can be summarized as follows:
- Converts HTML to GFM Markdown.
- Converts Markdown to whitelist-safe HTML.
- Normalizes HTML tables or pipe-delimited text into GFM tables.
- Generates nested tables of contents from Markdown headings.
- Zero-dependency, pure-function, hand-written lightweight parser.
Core Features¶
The plugin registers the markdown tool and distinguishes different actions via action.
Common actions include:
action=html2md: Takes an HTML snippet and outputs GFM Markdown.action=md2html: Takes Markdown and outputs whitelist-safe HTML.action=table: Takes an HTML<table>or pipe-delimited text and outputs a GFM table.action=toc: Takes Markdown headings and outputs a nested table of contents.
Tool parameters include:
action: Selectshtml2md,md2html,table, ortoc.html: Input forhtml2md.markdown: Input formd2htmlandtoc.text: Input fortable.maxBytes: Input limit, default 256KB, hard cap 1MB; errors on exceeding limit without truncation.
Safety and Boundaries¶
This plugin imposes clear constraints on both input and output.
Zero execution surface:
- No
eval. - No
new Function. - No loading of remote resources.
- No CSS layout parsing.
Content stripping:
scriptstyleiframeobjectnoscript
The above content is stripped entirely.
md2html specifics:
- Only whitelisted tags are output.
- All text is HTML-escaped.
Link handling:
- Link scheme whitelist is
http,https,mailto. javascriptanddatalinks are degraded to plain text.
Resource limits:
- Errors when nesting depth reaches 64 levels.
- Input
maxBytesdefaults to 256KB, hard cap 1MB. - Errors on input exceeding limit, without truncation.
Installation and Verification¶
Installation¶
The verified installation command is:
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-markdown
Note that web and headless are different profiles. Installing on web does not automatically overwrite headless. dsh run uses the headless profile by default, so for one-off task scenarios, installing on the headless profile is more common.
Checking Configuration¶
You can use the following command to check whether tool-markdown appears in the profile configuration:
dsh --profile web --dump-config | grep tool-markdown
Runtime Verification¶
You can trigger a simple conversion using dsh run:
dsh run "使用 markdown 工具把 <h1>标题</h1> 转成 Markdown"
Typical Usage¶
HTML to Markdown¶
Suitable for scenarios where users paste HTML snippets, email bodies, or exported files and want to get GFM Markdown.
Invocation:
action=html2md
html=<HTML 片段>
Output is GFM Markdown.
Markdown to HTML¶
Suitable for scenarios where Markdown needs to be rendered as controlled HTML.
Invocation:
action=md2html
markdown=<Markdown 文本>
Output is whitelist-safe HTML. Text will be HTML-escaped.
Table Normalization¶
Suitable for scenarios where the input is an HTML <table> or pipe-delimited text, and the desired output is a stable GFM table.
Invocation:
action=table
text=<HTML <table> 或管道分隔文本>
Output is a GFM table.
Table of Contents Generation¶
Suitable for generating a nested table of contents based on Markdown headings.
Invocation:
action=toc
markdown=<包含标题的 Markdown>
Output is a nested table of contents.
Compatibility and Runtime Requirements¶
Verified runtime and dependency information:
- Node engines:
^22.19.0 || >=24.0.0 - packageManager:
npm@11.16.0 peerDependencies:@deepseek-ai/cordis ^4.0.1@deepseek-ai/dsh-invariants >=0.0.1-rc.1 <0.2.0@deepseek-ai/dsh-tools >=0.0.1-rc.1 <0.2.0- Migrated and verified compatible with DSH
0.1.2-alpha.1 package.jsonversion:0.0.1private: trueinpackage.json- Startup method:
npx -p @deepseek-ai/dsh@next dsh web
This startup method is the lib production mode; documentation notes not to use install -g for global installation.
Notes¶
The plugin runs with the permissions of the current DSH process. Source code and license should be reviewed before installation.
Additionally, tool parameters are recorded in session logs. Do not pass HTML containing keys, session data, or other sensitive information directly to actions like html2md, md2html, or table.
Summary¶
The value of omdsh-dev/dsh-tool-markdown lies in consolidating common document conversions—HTML, Markdown, GFM tables, and tables of contents—into a single markdown tool, while reducing the risks of uncontrolled rendering through whitelist output, content stripping, scheme filtering, and input limits.
GitHub repository:
