dsh-md-export

Readme

# dsh-md-export

> 简体中文：[README.zh.md](README.zh.md)

DSH (DeepSeek Harness) Web plugin — **Markdown export extension for dsh-better-sidebar**.

Adds an **Export** button to the Markdown file viewer toolbar in better-sidebar. Click it to open a dropdown with two choices:

- 📄 **Save HTML (same directory)** — Renders the current `.md` file into a standalone `.html` and **writes it directly next to the .md file** (Markdown tables / code blocks / **Mermaid diagrams** all inlined; layout follows the original md preview theme — not A4 print-oriented)
- 🖨️ **Export PDF (print)** — Opens the browser print dialog (the printed content is the rendered document); choose "Save as PDF" to produce a PDF

## Features

- **Zero-dependency, keeps built-in behavior**: does not replace better-sidebar's built-in Markdown preview/edit (preview, edit, save and Mermaid rendering all remain); it only **appends** an export button to the toolbar
- **What you see is what you get**: the exported HTML is taken directly from the built-in previewer's rendered DOM (including Mermaid SVG) — no second rendering pass
- **Saves next to the .md**: writes the HTML into the md's directory via better-sidebar's `/sidebar/api/fs.write` channel (same basename, `.html` extension); falls back to a browser download if session detection fails
- **Layout follows the original md preview**: the exported HTML uses the current preview theme's colors and typography (dark/light auto-follow), content width adapts — **no A4 paper size**
- **Edit-mode friendly**: if you are in edit mode with unsaved content, export automatically switches to preview first
- **Auto-follow**: the button appears on the Markdown toolbar whenever the file or preview/edit mode changes

## Prerequisites

- DSH `dsh web` running
- [dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar) installed (or the aggregator package `@linxin666/dsh-web-ui-all` that brings it in)

## Install

```sh
dsh plugin --profile web add <dsh-md-export-0.1.0.tgz>
```

After installing, **restart dsh web** (a new bundle needs a host-side reload), then hard-refresh the browser (Cmd/Ctrl+Shift+R).

> Open any `.md` file in the sidebar — the "Export ▾" button appears right next to the "Preview | Edit" toggle.

## Usage

1. Open any `.md` file in better-sidebar (e.g. `docs/AOI端保存图片逻辑.md`)
2. Click the "Export ▾" button on the toolbar
3. Choose:
   - **Save HTML (same dir)**: the HTML is written next to the md (e.g. `docs/AOI端保存图片逻辑.html`), layout matches the md preview
   - **Export PDF (print)**: the print dialog opens; choose "Save as PDF"

## Development

```sh
node --check lib/client.js   # syntax check (hand-written single-file client bundle, no build step)
```

- `lib/index.js` — host-side placeholder plugin (empty `apply`, so the loader entry mounts)
- `lib/client.js` — client logic: MutationObserver watches the markdown toolbar → injects the export button + dropdown → grabs the preview DOM → saves next to the md via `/sidebar/api/fs.write` / triggers print

## Implementation notes

| Step | How |
|---|---|
| Button injection | `MutationObserver` watches `document.body`, finds `.nArs4W_editorModeToggle` (Markdown/HTML previewer toolbar) and injects when the current file is `.md` |
| Path resolution | Takes the md absolute path from the `.nArs4W_editorPathInput` `title` attribute; the output is the same directory + same basename + `.html` |
| Session detection | Scans `localStorage` keys `dsh-sidebar:v1:*`, picks the newest sessionId |
| Save to same dir | `POST /sidebar/api/fs.write` (payload: sessionId + absolute path + HTML content); falls back to a browser download on failure |
| HTML layout | Reads colors/fonts from `.nArs4W_editorMd` and the page theme; exported content width adapts (non-A4) |
| PDF export | Writes the same HTML into a hidden iframe → `window.print()` → user chooses "Save as PDF" in the print dialog |

## Known limitations

- PDF export relies on the browser print feature (Chrome/Edge both support "Save as PDF"); it does not generate a `.pdf` binary directly, so PDF cannot be saved to the md directory
- HTML save-to-same-dir depends on session detection (localStorage); in edge cases it falls back to a browser download
- Depends on better-sidebar's internal CSS class names (`nArs4W_` prefix); if a major better-sidebar upgrade changes the class names, this plugin needs a sync update
- Only applies to `.md` files; `.markdown` extension is also supported

## License

MIT