---
name: sn-md-to-html-report
description: 将 Markdown 文档转换为美观、舒适、结构清晰、可直接打开的 HTML 长篇报告。适用于把 .md 文件转成 HTML、统一研究报告/行业报告/调研文档版式、生成可离线分享的单文件网页报告、嵌入或校验本地图片、修复 Markdown 表格分隔符导致的错列问题，或优化已有 HTML 报告的阅读留白、图片呈现、目录导航、表格响应式和打印样式。
---

# Markdown 转 HTML 报告

## 默认目标

生成“长篇研究报告阅读版”HTML：正文舒展、图片自然插入、表格清晰、目录可用、可离线打开。优先保持内容可信和阅读舒服，不做营销页、不做炫技页面。

## 推荐路径

优先使用内置脚本生成稳定结果：

```bash
python3 /path/to/sn-md-to-html-report/scripts/render_report.py input.md output.html
```

常用参数：

- `--embed-images`：将本地图片嵌入 HTML，适合单文件分享。默认开启。
- `--no-embed-images`：保留相对图片路径，适合文件夹整体发布。
- `--with-js`：加入阅读进度、目录高亮、返回顶部等轻量交互。
- `--keep-inline-toc`：保留 Markdown 正文中已有的目录；默认会移除正文目录，避免和侧边栏目录重复。
- `--mermaid-source auto|cdn|local|none`：渲染 Markdown 中的 Mermaid 代码块。默认 `auto`，检测到 ```mermaid 代码块时使用 CDN；`local` 会引用输出 HTML 同目录下的 `mermaid.min.js`；`none` 保留为普通代码块。
- `--title-style comfortable`：默认舒适报告模板。

生成后运行图片检查：

```bash
python3 /path/to/sn-md-to-html-report/scripts/check_image_refs.py output.html
```

当输出使用 `--embed-images` 时，检查结果中的本地图片引用数通常为 0，这是正常的。

## 工作流程

1. 确定输入 Markdown 和输出 HTML。
   - 用户只给输入路径时，在同目录生成同名 `.html`。
   - 若同名 HTML 已存在，优先换新文件名，除非用户明确要求覆盖。
2. 转换前检查 Markdown。
   - 以 Markdown 所在目录作为相对图片基准。
   - 将误用的全角表格竖线 `｜` 修正为半角 `|`，避免表格错列。
   - 对“说明文字：”后紧跟 `-`、`*` 或数字编号列表但中间缺空行的常见写法，转换前补空行，让分点输出渲染为真正列表。
   - 如果 Markdown 已有 `## 目录` 且内容是章节锚点列表，默认从正文中移除；侧边栏目录已经提供导航，正文目录会重复占空间。
   - 保留原文内容，不总结、不改写、不新增事实。
3. 生成完整 HTML5。
   - CSS 内联到 `<style>`，不依赖 CDN、在线字体、外部 CSS。
   - 默认不需要 JavaScript；只有用户想要阅读进度、目录高亮、返回顶部时加少量原生 JS。
   - Markdown 中的 ```mermaid 代码块会转换为 Mermaid 图表容器；如需完全离线分享，使用 `--mermaid-source local` 并将 `mermaid.min.js` 放在输出 HTML 同目录。
   - 图片默认嵌入为 `data:image/...`，让 HTML 单文件可独立打开。
4. 自检输出。
   - 检查标题、目录、表格数量、图片数量是否与源文档大体一致。
   - 检查宽表在移动端可横向滚动，图片不撑破页面。
   - 检查 HTML 属性、闭合标签、目录锚点和 CSS 语法。

## 视觉原则

从这次效果中沉淀的默认偏好：

- 页面像“干净的研究报告”，不是后台表格页，也不是营销落地页。
- 使用浅灰页面背景和白色正文纸张区，正文有明确边界但不过度卡片化。
- 桌面端左侧使用粘性目录，正文在右侧；移动端目录放到正文上方或可折叠。
- 正文中已有的 Markdown 目录默认不保留，除非用户明确需要正文目录或使用 `--keep-inline-toc`。
- H1 可以使用克制的蓝绿渐变标题区，正文标题保持清晰层级。
- 正文留白要舒适：段落、表格、图片之间要让读者有停顿。
- 图片作为图表节点自然出现：居中、最大宽度 100%、轻边框、轻阴影、与上下文留足间距。
- 表格适合研究报告扫描：表头浅色或深色皆可，但要稳定、可横向滚动、单元格内边距足够。
- 配色避免单一深蓝/紫色压满页面；推荐蓝绿主色配少量蓝色链接。

## 舒适模板要点

默认 CSS 应接近以下参数，可按内容微调：

- `body`：`line-height: 1.75`，浅灰背景，系统中文字体。
- `.layout`：桌面端 `grid-template-columns: minmax(220px, 280px) minmax(0, 1fr)`，最大宽度约 `1480px`，页面外边距约 `28px`。
- `.toc-panel`：粘性、半透明白底、细边框、轻阴影；目录项字号约 `13px`。
- `main`：白色正文容器、`8px` 圆角、细边框、轻阴影。
- `article`：桌面端内边距约 `46px min(6vw, 76px) 68px`。
- `h1`：标题区可用 `linear-gradient(135deg, #0f766e, #155e75, #1d4ed8)`，字号 `clamp(30px, 4vw, 52px)`。
- `h2`：上方留足空间，顶部细分割线，字号 `clamp(22px, 2.3vw, 30px)`。
- `h3`：字号约 `21px`，颜色比正文更深。
- `blockquote`：用浅蓝绿背景和左侧强调线，可承载图注或注释。
- `.table-scroll`：作为表格外层滚动容器，`width:100%`、`overflow-x:auto`、细边框和圆角。
- `table`：保持原生 `display:table` 和 `width:100%`，不要用 `display:block`；短表要自然铺满正文宽度，宽表由 `.table-scroll` 横向滚动。
- `img`：`display:block; max-width:100%; height:auto; margin:24px auto 8px; border:1px solid var(--line); border-radius:8px; box-shadow:0 12px 28px rgba(15,23,42,.08)`。

## 图片规则

- 默认嵌入本地图片，适合给别人发一个 HTML 文件。
- 用户要求保持文件较小、图片可替换、或已有发布目录时，使用 `--no-embed-images` 保留相对路径。
- 不要使用绝对本地路径写入 HTML，除非用户明确要求。
- Markdown 图片后的引用块若明显是图注，保留为图下说明或 blockquote，不改变文字。
- 缺失图片要在最终回复里说明路径。

## 表格规则

- 修复全角竖线 `｜`。
- 修复列表前缺空行导致的 Markdown 分点不渲染问题；不要碰代码块里的内容。
- 使用 Markdown 解析器或结构化转换，不用脆弱的字符串拼 HTML 表格。
- 宽表必须可横向滚动，不能挤压正文，也不能在移动端撑破页面。
- 短表不要在右侧留下大片空白；表格元素保持 `width:100%`，滚动只放在外层容器。
- 不要为了美化删列、合并列或改写单元格内容。

## 交互规则

默认静态 HTML 已足够。只有在用户要求“导航更方便”“像原报告一样有进度条”或文档特别长时，加入 `--with-js`：

- 阅读进度条。
- 当前目录项高亮。
- 返回顶部按钮。
- 移动端目录展开/收起。

所有交互使用原生 JavaScript，不依赖外部库；脚本要先检查元素存在。

## 打印规则

添加 `@media print`：

- 隐藏目录、进度条、返回顶部等辅助 UI。
- 页面背景改白，去掉阴影。
- 尽量避免表格、图片、引用块被不自然截断。
- 打印时标题不依赖深色渐变背景。

## 质量自检

生成后至少确认：

- HTML 文件存在且可读。
- `<table>`、`<img>` 数量与源文档大体一致。
- 分点内容应渲染为 `<ul>/<ol>` 和 `<li>`，不要保留成带连字符的普通段落。
- 表格应由 `.table-scroll` 包裹，`table` 自身不要使用 `display:block`。
- 嵌入图片时包含 `data:image/`；非嵌入时 `check_image_refs.py` 无缺失图片。
- 目录链接均为 `href="#..."` 且目标 ID 存在。
- 正文不应同时出现一份原始 Markdown 目录和一份侧边栏目录，除非用户明确要求保留。
- 不出现破损标签、空 `href`、重复明显 ID、非法 `calc()` 或损坏 CSS。

## 最终回复

简洁说明：

- 输出 HTML 路径。
- 是否嵌入图片，或图片引用检查结果。
- 修复了哪些格式问题，例如全角表格竖线。
- 未能完成的校验，如有。