dsh-md-viewer

Readme

# dsh-md-viewer

<div align="center">
  <a href="https://www.npmjs.com/package/dsh-md-viewer"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-md-viewer" /></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
  <a href="https://dshfind.com/zh/plugins/2017java/dsh-md-viewer?ref=badge"><img alt="dshfind" src="https://dshfind.com/api/badge/2017java/dsh-md-viewer?lang=zh" /></a><br />
  <b>在 DSH 的 dsh-better-sidebar 侧边栏里，把 .md 文档渲染成漂亮的富预览。</b>
</div>

把 Markdown（`.md` / `.markdown`）文件在 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 的布局融合侧边栏里以**富渲染预览**打开——标题、表格、代码块、徽章图片、剥离 HTML 注释，不浮层、不遮挡会话、小屏友好、宽度可拖拽。

> 与 dsh-better-sidebar 内置的 Markdown **编辑器**不同，本插件提供的是开箱即用的**渲染预览**：点开即是排版好的文档，无需切换预览模式。

## ✨ 功能

- 🎨 完整渲染：标题/段落/列表/引用/分隔线/链接/图片/代码块/**管道表格**
- 🌈 代码块：**语法高亮**（js/ts/py/bash/json/yaml/html/css）、语言徽标、**一键复制**
- 🧭 **目录 TOC**：自动收集标题层级，点条目平滑滚动
- 🛡️ 常见 HTML 处理：`<img>`→图片、`<a>`→链接、`<br>`、`<!-- 注释 -->` 剥离、HTML 实体反转义
- 🔒 安全：纯 React 渲染、无 `innerHTML`、不执行内嵌 HTML
- 🔗 对话内联动：DSH 每轮"产出文件"chips / 文件树里点开 `.md` → 直接进侧边栏预览
- 🧩 依赖 dsh-better-sidebar 的 `registerFileViewer` 服务，作为"文件预览器"注册（exts: `md`/`markdown`）

## 🚀 安装

> ⚠️ **本插件依赖 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)**（通过它的 `ctx.betterSidebar` 服务注册文件预览器）。不装 better-sidebar 则本插件不生效（安全 no-op）。
> **不需要 better-sidebar？** 用独立的 **`dsh-md-overlay`**（浮层预览，不依赖 better-sidebar）。

**前置**：DSH（`dsh web` 可运行）、已装 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)（`dsh plugin --profile web add dsh-better-sidebar@latest`）。

```sh
dsh plugin --profile web add dsh-md-viewer@latest
```

装完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）。之后在 dsh-better-sidebar 里打开任意 `.md` 文件即可看到渲染预览。

## 🔌 机制

- 本插件为 **client-only**（Host 半为 no-op 桩）。
- `package.json` 的 `dsh.client.platform: "web"` + `exports["./client"]` 让 DSH 客户端模块系统加载 `lib/client.js`。
- `lib/client.js` 的 `apply()` 调用 `ctx.betterSidebar.registerFileViewer({ exts: ["md","markdown"], fetchStrategy: "fsRead", component })`，把 .md 打开行为接管为富渲染预览。
- 对话里 DSH 自带的"产出文件"chips 点击 → `openPath` → 被 dsh-better-sidebar 拦截 → 用本查看器渲染。

## 🛠️ 开发

仓库结构与 DSH 官方插件规范一致：单 npm 包、双 client bundle（`__ModuleLoader__.load`），运行期不依赖 npm / checkout。

```sh
# 本地安装（file: 链接）
cd ~/.dsh/profiles/web
npm install --save file:D:/DSH/dsh-md-viewer   # 或你的实际路径
# 在 package.json 的 dsh.profile.bundles 追加 "dsh-md-viewer"
```

## ⚠️ 已知限制

- markdown 内**相对路径图片**不会相对文件目录解析（需要时可在 component 里基于 `props.path` 重写 src）；
- 不支持 GFM 任务列表 / LaTeX / Mermaid / 脚注（需要更完整的独立渲染时，用 **`dsh-md-overlay`**，支持任务清单/嵌套列表/停靠面板）。

## 📦 发布

见 [PUBLISHING.md](../PUBLISHING.md)（npm 发布 + dshfind 插件超市收录的完整流程）。

## 📄 License

MIT