<p align="center">

<a href="#english">English</a>&nbsp;&nbsp;|&nbsp;&nbsp;

<a href="#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87">简体中文</a> </p>

<br>

DSH Markdown Previewer / DSH Markdown 预览器

<p align="center"> <b>DSH web GUI client plugin: sidebar Markdown preview — browse, render, edit &amp; save.</b><br> <b>DSH web GUI 客户端插件：侧栏 Markdown 预览 —— 浏览、渲染、编辑与保存。</b> </p>

---

English

A client plugin for the DSH web GUI: adds an "MD preview" button at the bottom of the sidebar. Clicking it opens a floating preview window where you can browse, render, and edit & save Markdown files.

Features

• Directory browsing: lists subdirectories and .md files; enter a directory / open a file by clicking, .. to go up;
• Dual view — rendered / source (built-in zero-dependency Markdown renderer: headings, lists, tables, code blocks, quotes, links, inline styles);
• Editable source view: save via the "Save" button or Ctrl/Cmd+S; unsaved changes are flagged in the title bar; switching files / closing the window asks for confirmation;
• Save with mtime conflict detection: if the file changed on disk in the meantime, you get a 409 prompt to refresh instead of a silent overwrite;
• Path input: type any absolute path (directory or .md file) and press Enter to jump;
• Custom backdrop: solid color, local image (auto canvas-compressed above 1.5 MB) or local video (≤ 50 MB, tiled as a muted looping <video> background, current page session only);
• Custom text color: pick the body text color in the backdrop panel; when unset, light/dark is derived from backdrop luminance; applies to body, lists, and the editor — not just headings;
• Image/color backdrop persisted in localStorage, with a one-click "restore theme default";
• Draggable title bar; double-click to reset to the default dock (position remembered in sessionStorage);
• Opens the current session's workspace directory by default; Esc or ✕ closes; refresh button re-reads the file.

Security boundaries

• The host half registers only /md-preview-prefixed routes; read/list are GET/HEAD only, write is POST only;
• File access is limited to .md / .markdown / .mdown extensions, content ≤ 2 MB; write request body ≤ 3 MB;
• Writes go through temp file + rename atomic replacement — an interrupted write never leaves a half file;
• Writes carry mtime conflict detection (409) to prevent clobbering unsynchronized external edits;
• Directory listings show only directories and md files;
• Accessible paths = whatever the local shell can read/write (the GUI listens on 127.0.0.1 by default).

Files

Install

Install the official runtime with Node.js:

npx @deepseek-ai/dsh web

Install this plugin into a profile (the ecosystem convention):

dsh plugin --profile web add "github:anitman/dsh-plugin-md-preview#main"

The #<ref> suffix selects a branch, tag, or commit: #main follows the default branch; pin #<sha> or a release tag to make the installed content immutable; omit it to track the repo's default branch.

dsh plugin forwards package operations to pnpm, so npm, Git/GitHub, local path, file: and link: package specs are all supported — e.g. from a local clone:

dsh plugin --profile web add .

Only packages declaring dsh.bundle.patch become active profile layers; this package declares it, so dsh plugin add completes the link and layer activation in one step. Pure JS, no build scripts — a git install needs no allowBuilds approval.

Restart dsh --profile web after installing or updating a bundle: the document icon button then appears at the bottom of the sidebar (above the settings button); manage it under Settings → Plugins.

#### Uninstall

dsh plugin --profile web remove dsh-plugin-md-preview

Removes the dependency and the patch layer together; restart dsh to take effect.

#### Manual fallback (without the dsh CLI)

1. Create a symlink dsh-plugin-md-preview in ~/.dsh/profiles/web/node_modules/ pointing at this directory (or copy the directory if symlinks fail); 2. Add to dependencies in ~/.dsh/profiles/web/package.json: "dsh-plugin-md-preview": "file:<absolute path to this repo>"; 3. Append to the top-level array of ~/.dsh/profiles/web/cordis.patch.yml: ``yaml - insert: - id: md-preview name: "dsh-plugin-md-preview" `` 4. Restart the dsh process (new Loader rows are only scanned at startup; sessions restore automatically).

Updating

• Only client.js changed: no restart needed, client-HMR hot-reloads the plugin (requires the host-side watch chain to be active; otherwise refresh the page);
• index.js (host half) changed: dsh restart required;
• Local clone installed via add .: git pull, then restart dsh;
• Installed via github:: re-run the install command with a new #ref to upgrade;
• If node_modules holds a copy instead of a symlink: re-copy after changes (or switch back to a symlink).

---

简体中文

DSH web GUI 客户端插件：侧栏底部多一个「MD 预览」按钮，点开是一个浮动预览窗口，可直接浏览、渲染并编辑保存 Markdown 文件。

功能

• 目录浏览：列出子目录和 .md 文件，点击进入 / 点击文件打开，.. 回上级；
• 渲染 / 源码双视图（内置零依赖 Markdown 渲染器：标题、列表、表格、代码块、引用、链接、行内样式）；
• 源码视图可编辑：点「保存」或按 Ctrl/Cmd+S 写回磁盘；有未保存修改时标题栏显示「保存 ●」，切换文件 / 关窗前会弹确认；
• 保存带 mtime 冲突检测：若期间文件被外部改过，返回 409 提示刷新后重试，避免误覆盖；
• 路径输入框：直接输入任意绝对路径（目录或 .md 文件）回车跳转；
• 自定义背景：标题栏「背景」按钮可选纯色、本地图片（>1.5MB 自动 canvas 压缩）或本地视频（≤50MB，<video> 铺底循环静音播放，仅当前页面会话有效）；
• 自定义文字颜色：背景面板里可选正文文字色，不设则按背景亮度自动取深浅；作用范围覆盖正文 / 列表 / 编辑区，不只标题；
• 图片/颜色背景存 localStorage，可「恢复主题默认」一键还原；
• 标题栏可拖动，双击复位到默认停靠位（位置记忆在 sessionStorage）；
• 默认打开当前会话的工作区目录；Esc 或 ✕ 关闭；刷新按钮重读文件。

安全边界

• 宿主半边只注册 /md-preview 前缀路由；read/list 仅 GET/HEAD，write 仅 POST；
• 读/写文件都只允许 .md / .markdown / .mdown 扩展名，且内容 ≤ 2MB；write 请求体 ≤ 3MB；
• write 通过临时文件 + rename 原子替换，中断不会留下半截文件；
• write 带 mtime 冲突检测（409），防止覆盖未同步的外部修改；
• 列目录只显示目录与 md 文件；
• 路径可访问范围 = 本机 shell 可读写范围（GUI 默认只听 127.0.0.1）。

文件

安装

用 Node.js 安装官方运行时：

npx @deepseek-ai/dsh web

把本插件装进 profile（生态标准写法）：

dsh plugin --profile web add "github:anitman/dsh-plugin-md-preview#main"

#<ref> 后缀可选分支、tag 或 commit：#main 跟随默认分支；锁 #<sha> 或 release tag 可让安装内容不可变；省略则跟随仓库默认分支。

dsh plugin 把包操作转发给 pnpm，因此 npm、Git/GitHub、本地路径、file: 与 link: 包规范都支持——例如从本地 clone 安装：

dsh plugin --profile web add .

声明了 dsh.bundle.patch 的包才会成为激活的 profile 层；本包已声明，dsh plugin add 一步完成链接与补丁层激活。纯 JS 无构建脚本，git 安装不需要 allowBuilds 授权。

安装或更新后重启 dsh --profile web：GUI 左侧栏底部（设置按钮上方）会出现文档图标按钮；管理入口在设置 → 插件。

#### 卸载

dsh plugin --profile web remove dsh-plugin-md-preview

同时移除依赖和补丁层，重启 dsh 生效。

#### 手动安装（fallback，无 dsh CLI 时）

1. 在 ~/.dsh/profiles/web/node_modules/ 下创建指向本目录的符号链接 dsh-plugin-md-preview（失败则直接拷贝本目录）； 2. 在 ~/.dsh/profiles/web/package.json 的 dependencies 加："dsh-plugin-md-preview": "file:<本机此仓库的绝对路径>"； 3. 在 ~/.dsh/profiles/web/cordis.patch.yml 顶层数组追加： ``yaml - insert: - id: md-preview name: "dsh-plugin-md-preview" `` 4. 重启 dsh 进程（新增 Loader 条目只在启动时扫描；会话会自动恢复）。

更新

• 只改 client.js：无需重启，client-HMR 会自动热重载插件（需要宿主侧 watch 链生效；否则刷新页面）；
• 改 index.js（宿主半边）：必须重启 dsh；
• 本地 clone 通过 add . 安装的：git pull 后重启 dsh；
• github: 安装的：用新的 #ref 重新执行安装命令升级；
• 若 node_modules 里是拷贝而非符号链接：修改后需重新拷贝（或改回符号链接）。