poiuyjie/dsh-md-preview

Click a .md in your conversation — no more jumping to VSCode. Open a side-by-side preview on the right and read on.

⚡ Core experience — side-by-side with your conversation: keep chatting, writing and proofreading on the left while the .md source you clicked renders live, side-by-side in the same window on the right — what you see is what you wrote, no window switching; dark/light theme follows the shell automatically.

A DeepSeek Harness (DSH) plugin that adds an MD Preview entry to the session header, tracks the .md files your session has read or written, and opens an in-chat .md reference side-by-side in the right panel instead of launching the system editor (e.g. VSCode).

Built with dsh-vision-opencode

This plugin pairs with dsh-vision-opencode — and was developed and polished on top of that vision plugin. Together they make a much stronger workflow:

• Visual-verification loop: dsh-vision-opencode gives a text-only main model image understanding (vision_read_image), so the model can "see" rendered document pages; this plugin then opens the corresponding .md source side-by-side on the right — look at the rendered image, compare against the source, revise, verify, and record in one flow
• Image-to-source comparison: the left conversation stream holds the visual verdicts ("Table III renders cleanly, no overflow"), while the right panel holds the Markdown source — review and edit side by side
• Great for document / paper workflows: LaTeX build checks, layout QA, revision records — visual confirmation plus source preview in split view

Install them together (prefer the native DSH plugin commands: they download the sources from GitHub, register the packages into the profile's dsh.profile.bundles layer and apply each cordis.patch.yml automatically — hand-editing package.json with npm pkg set neither downloads anything nor registers the layer, so the plugin won't take effect):

dsh plugin --profile web add github:poiuyjie/dsh-vision-opencode
dsh plugin --profile web add github:poiuyjie/dsh-md-preview

💡 On Windows use dsh.ps1 instead of dsh (or powershell dsh.ps1); the profile directory is %USERPROFILE%\.dsh\profiles\web.

Features

• Side-by-side preview: click a .md reference in the conversation (produced-file chips / inline references / tool-card paths) to open it in the right panel — top-aligned with the conversation content, draggable width (up to about half the screen), layout yields automatically without covering the chat
• Per-session recent list: automatically collects the .md files your session read/wrote (read/write/edit/delete + time + file mtime); each session only sees files it actually touched — no cross-session leakage
• Two display modes:
  • Floating window: draggable, resizable, position/size remembered (localStorage)
  • Docked right panel: side-by-side with the conversation, drag the left divider to resize
• Modifier-key escape hatch: hold Ctrl/Cmd/Shift while clicking a .md reference to open it with the system default app (VSCode) instead
• Manual open: type a workspace-relative .md path to preview it
• Full Markdown rendering: headings / lists / tables / code blocks / quotes / inline code / math snippets / image links
• Full-page tab: also available as a "MD Preview" tab in the Conversation/Trajectory bar

System support

⚠️ Prefer the native dsh plugin install (dsh on Linux/macOS, dsh.ps1 on Windows). The manual route (clone + npm install + edit cordis.patch.yml) has been verified on Ubuntu (DSH 0.1.0-rc.6) and Windows; on other distros the install paths, the ~/.dsh profile directory, and the cordis.patch.yml syntax may differ — adapt to your environment.

Installation

Option 0: dsh plugin add (native, recommended)

The package declares a dsh.bundle manifest and ships its own cordis.patch.yml, so it installs with the native plugin command (auto-applied as a profile layer — no manual cordis.patch.yml edits needed):

dsh plugin --profile web add github:poiuyjie/dsh-md-preview

⚠️ Don't substitute npm pkg set "dependencies.xxx=...": it only edits one field of package.json — it neither downloads the package nor registers it into the dsh.profile.bundles layer, so dsh web won't pick it up. dsh plugin add does both (download + register the layer, applying cordis.patch.yml for you).

Option 1: Clone locally (recommended — easy to edit and to follow updates)

Clone from GitHub (example: ~/plugins):

mkdir -p ~/plugins && cd ~/plugins
git clone https://github.com/poiuyjie/dsh-md-preview.git
cd dsh-md-preview

Then reference the local path from your DSH web profile (Ubuntu: ~/.dsh/profiles/web):

cd ~/.dsh/profiles/web
npm pkg set "dependencies.dsh-md-preview=file:~/plugins/dsh-md-preview"
npm install

Option 2: Reference GitHub directly (no clone, quick)

cd ~/.dsh/profiles/web
npm pkg set "dependencies.dsh-md-preview=github:poiuyjie/dsh-md-preview"
npm install

Enable the plugin manually (Option 1 / Option 2 only — dsh plugin add does this automatically)

Add an entry to the profile's cordis.patch.yml:

- insert:
    - id: md-preview
      name: 'dsh-md-preview'

Restart dsh web and refresh the page — you'll see the MD Preview button in the session header.

Tip: with Option 1, git pull in the cloned repo follows updates; the plugin is plain JS with no build step — after editing code, a page refresh is enough for the client half (HMR supported).

Uninstall

From the profile directory (Ubuntu: ~/.dsh/profiles/web):

cd ~/.dsh/profiles/web
npm pkg delete dependencies.dsh-md-preview
npm install

(If you installed via Option 1, the dependency is removed automatically; for a full cleanup also run rm -rf ~/plugins/dsh-md-preview.)

Then remove the insert entry from cordis.patch.yml:

# Remove this block:
- insert:
    - id: md-preview
      name: 'dsh-md-preview'

Finally restart dsh web. Uninstalling never deletes your .md files or session history — it only removes the preview panel.

Usage

1. Click the MD Preview button in the session header to open the panel;
2. The panel shows your session's recently accessed .md files (name / path / op history / snippet);
3. Click a .md reference in the message stream → the right panel opens and loads that file automatically;
4. Drag the divider on the panel's left edge to resize; click "浮动" (Float) to switch to a floating window; click "✕" to close;
5. Hold Ctrl/Cmd/Shift while clicking a reference → opens with your system default editor.

Development

# The plugin itself (Host half + Client half, plain JS, no build step)
ls index.js client.js

• index.js — Host half. Listens to fs/observed to record md file access (isolated per session), serves /md-preview/api/{recent,read,peek} HTTP endpoints
• client.js — Client half. Panel UI, click interception (capture-phase detection of md reference buttons), right-dock + layout yielding

License

MIT