sn-md-to-html-report · diff
git:20260428.616e7c2 to git:20260630.4afb99c
55 added, 126 removed. Audit A to A.
---
name: sn-md-to-html-report
- description: 将 Markdown 文档转换为美观、舒适、结构清晰、可直接打开的 HTML 长篇报告。适用于把 .md 文件转成 HTML、统一研究报告/行业报告/调研文档版式、生成可离线分享的单文件网页报告、嵌入或校验本地图片、修复 Markdown 表格分隔符导致的错列问题，或优化已有 HTML 报告的阅读留白、图片呈现、目录导航、表格响应式和打印样式。
+ description: 将 Markdown 报告、研究笔记、行业分析、战略备忘录、技术白皮书、复盘、周报等长文档，重组并创作为有编辑判断、网页美感和证据秩序的自包含 HTML 专题页。用户要求“转成 HTML”“网页化报告”“美化报告”“做成专题页”“便于分享”“提升可读性/设计感”“把报告做成网页”时使用。必须先写 plan.md 再写 HTML，保留原文事实断言和结论强度，不套模板，不做机械 Markdown 转换。
---
- # 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)`。
-
- ## 图片规则
+ # Report HTML
- - 默认嵌入本地图片，适合给别人发一个 HTML 文件。
- - 用户要求保持文件较小、图片可替换、或已有发布目录时，使用 `--no-embed-images` 保留相对路径。
- - 不要使用绝对本地路径写入 HTML，除非用户明确要求。
- - Markdown 图片后的引用块若明显是图注，保留为图下说明或 blockquote，不改变文字。
- - 缺失图片要在最终回复里说明路径。
+ 把报告文本创作为一份有编辑判断、网页美感、证据秩序、且只属于这份主题的单文件 HTML。
- ## 表格规则
+ 核心原则：**保留事实断言，重构阅读和视觉体验，让设计从报告所属领域和内容任务里长出来。主题自己的世界——它的材质、工具、器物与语汇——是产生独特设计选择的来源。**
- - 修复全角竖线 `｜`。
- - 修复列表前缺空行导致的 Markdown 分点不渲染问题；不要碰代码块里的内容。
- - 使用 Markdown 解析器或结构化转换，不用脆弱的字符串拼 HTML 表格。
- - 宽表必须可横向滚动，不能挤压正文，也不能在移动端撑破页面。
- - 短表不要在右侧留下大片空白；表格元素保持 `width:100%`，滚动只放在外层容器。
- - 不要为了美化删列、合并列或改写单元格内容。
+ ## 设计判断原则
- ## 交互规则
+ - **首屏即论点**：首屏先找到这份报告所属领域里最有识别度、最能承载主题气质的事物或机制，并用最适合它的形式呈现：标题、图片、动画、实时演示或一个可互动瞬间。这个选择必须有明确判断；不要默认使用“大数字 + 小标签 + 辅助统计 + 渐变强调”，只有当它确实是主题最自然、最有力的入口时才使用。
+ - **文字系统承载页面性格**：标题字体与正文字体要被有意搭配，不要沿用任何项目都能套上的常用字体组合；同时建立清晰的字阶，并有意识地设置字重、字宽和间距。让文字排印本身成为设计中可被记住的一部分，而不是只负责传递内容的中性容器。
+ - **结构即信息**：编号、眉题、分隔线、标签等结构性手段，应该传递内容的真实信息，而不是装饰内容。许多通用设计都使用编号标记（01/02/03），但这仅适用于内容本身就是一个序列的情况——例如一个真实的流程或一份文字时间线，其中顺序承载着读者所需的信息。在使用编号标记之前，请先思考其是否真的有意义。
+ - **有意识地使用动效**：先判断动效是否能服务主题、阅读或信息理解，再决定用在哪里：页面加载序列、滚动触发展示、悬停微交互或环境氛围。一个被编排好的关键动效通常比零散特效更有力量；动效选择必须服从整体美学方向。有些主题更适合克制处理，额外动画反而会削弱专业感，并让页面显得像 AI 生成的模板作品。
+ - **复杂度匹配愿景**：视觉方向越繁复，执行就越需要足够的层次、细节和完成度；视觉方向越极简，间距、字阶、对齐和微细节就越要精准。优雅不等于少，也不等于多，而是把选定的方向执行到位。
+ - **认真处理文案**：标题、导语、标签、按钮和说明都要被当作设计的一部分处理。可以对源报告的内容重写、压缩、合并和组织表达，但不得发明事实、口径或结论强度。文案和视觉一样会产生模板感。
- 默认静态 HTML 已足够。只有在用户要求“导航更方便”“像原报告一样有进度条”或文档特别长时，加入 `--with-js`：
+ ## 设计知识的使用方式
- - 阅读进度条。
- - 当前目录项高亮。
- - 返回顶部按钮。
- - 移动端目录展开/收起。
+ - **层级**：先决定读者第一眼、第二眼、第三眼分别看什么，再分配尺度、重量、留白和位置。
+ - **对比**：用字体气质、字号、明暗、密度、动静和空间关系制造差异；不要只靠颜色强调。
+ - **对齐与网格**：正文、图表、卡片、注释和导航都落在同一套网格和宽度档里，避免右边缘和左基线随手漂移。
+ - **邻近与分组**：证据靠近判断，注释靠近对象，相关项成组，不相关项拉开。
+ - **重复与变奏**：重复建立秩序，变奏表达章节差异；整页不能一章一个系统，也不能每章完全同形。
+ - **图地关系**：纹理、背景、氛围和动效永远退到内容之后，不能抢走正文和证据的可读性。
+ - **节奏**：长报告要有轻重、疏密、转场和停顿；不是把所有模块等权堆叠。
- 所有交互使用原生 JavaScript，不依赖外部库；脚本要先检查元素存在。
+ ## 硬规则
- ## 打印规则
+ - Markdown 是素材，不是页面结构；不要逐段照搬，也不要把所有内容塞进卡片。
+ - 先写 `plan.md`，再写 HTML；没有完整 plan 不动 HTML。
+ - 页面默认是单文件 HTML：语义 HTML + 内联 CSS；除非用户要求或项目已有资源体系，不拆分文件、不引 CDN。
+ - 可以用领域隐喻组织视觉和结构，但页面里的数字、来源、案例、判断、结论强度必须来自原报告。
+ - 不发明 logo、客户、证言、排名、地图点位、图表数据、置信度或看似合理但原文无法支撑的归纳。
+ - 图表、流程、时间线、地图式分组等必须自包含手写。
- 添加 `@media print`：
+ ## 工作流
- - 隐藏目录、进度条、返回顶部等辅助 UI。
- - 页面背景改白，去掉阴影。
- - 尽量避免表格、图片、引用块被不自然截断。
- - 打印时标题不依赖深色渐变背景。
+ 1. **读内容与任务**：通读源报告，确认主题、领域、受众、用途、核心判断、证据、限制、重复内容、表格、图示和附录。
+ 2. **第一遍：brainstorm 短设计计划**：先根据 brief、报告领域、内容任务、证据结构和受众发散 2-3 个与内容契合的设计方向，不碰具体 HTML。每个方向用 compact token system 表达：Color 为 4-6 个命名 hex 值并说明语义用途；Type 定义 display、body，必要时定义 utility / mono；Layout 用一句话概念和 ASCII wireframe 描述；Signature 定义这页唯一会被记住的设计元素。
+ 3. **审查并修订短设计计划**：对照 brief 和报告内容检查每个方向是否真有内容来源。如果任何部分像类似页面的通用默认答案，而不是为当前报告做出的选择，必须修订该部分，并写明改了什么、为什么改。确认相对独特性后，选择 1 个方向进入完整计划。
+ 4. **第二遍：完整页面计划**：基于修订后的短设计计划，展开信息结构、首屏策略、页面拓扑、导航、章节版面、转场节奏和证据贴附方式；用层级、对比、对齐、邻近、分组、重复 / 变奏来组织信息。
+ 5. **逐章做内容设计**：每章写清 `内容形状 -> 章节版面 -> 呈现形式 -> 排版处理`。颗粒度到段或判断，不要整章放过；长论述也要做导语、拉引、边注或判断提块。
+ 6. **定设计契约与 checklist**：写 HTML 前把 tokens、字体角色、宽度档、章版面映射、动效策略、响应式降级、事实边界、泛模板自检和检查角度落到 `plan.md`。checklist 是开工前的契约，不是事后补救。
+ 7. **写 HTML**：只实现 `plan.md`，不要在 HTML 阶段另起一套视觉或结构。先搭全页骨架，再填内容和图表；所有颜色、字体和关键布局选择都必须从短设计计划派生。
+ 8. **按检查角度审查**：从事实保真、主题契合、美学一致性、字体层级、布局网格、内容塑形、动效克制、可访问性、响应式和分享性逐项检查；未通过就修正。
- ## 质量自检
+ ## plan.md 必须包含
- 生成后至少确认：
+ - 受众 / 用途：谁读，读完要做什么。
+ - 短设计计划：基于 brief 与内容信号 brainstorm 2-3 个方向；每个方向包含 Color、Type、Layout、Signature。
+ - 相对独特性审查：哪些部分像默认答案，改了什么，为什么改；确认后选择 1 个方向。
+ - 首屏策略：用什么主题领域代表物开篇，领读什么，如何形成焦点和图地关系。
+ - 信息结构与版式策略：拓扑、骨架、导航、章节版面、转场节奏、宽度档、移动端降级。
+ - 逐章内容设计表：每章的内容形状、章节版面、呈现形式、排版处理、证据贴附方式。
+ - 设计契约：tokens、字体角色、网格 / 宽度档、导航类型、章版面映射、动效策略、关键对比度、泛模板自检。
+ - checklist：写 HTML 前确认设计契约完整；交付前按检查角度逐项签收。
- - HTML 文件存在且可读。
- - `<table>`、`<img>` 数量与源文档大体一致。
- - 分点内容应渲染为 `<ul>/<ol>` 和 `<li>`，不要保留成带连字符的普通段落。
- - 表格应由 `.table-scroll` 包裹，`table` 自身不要使用 `display:block`。
- - 嵌入图片时包含 `data:image/`；非嵌入时 `check_image_refs.py` 无缺失图片。
- - 目录链接均为 `href="#..."` 且目标 ID 存在。
- - 正文不应同时出现一份原始 Markdown 目录和一份侧边栏目录，除非用户明确要求保留。
- - 不出现破损标签、空 `href`、重复明显 ID、非法 `calc()` 或损坏 CSS。
+ ## 参考文件
- ## 最终回复
+ - brainstorm 短设计计划前，读 `references/01-aesthetic-direction.md`。
+ - 定版式和逐章内容设计前，读 `references/02-layout-and-content-design.md`。
+ - 写 HTML 前，读 `references/03-design-contract.md` 并完成 checklist。
+ - 交付前，读 `references/04-review-angles.md` 并按角度审查。
- 简洁说明：
+ ## HTML 要求
- - 输出 HTML 路径。
- - 是否嵌入图片，或图片引用检查结果。
- - 修复了哪些格式问题，例如全角表格竖线。
- - 未能完成的校验，如有。
+ - 使用 CSS tokens 管理颜色、字体、间距、边线、宽度档和动效参数。
+ - 桌面端要真实使用横向空间；移动端无页面级横向滚动，长表和代码块可局部滚动。
+ - 导航若存在必须可用：锚点能跳、当前章可感知、键盘可达、小屏可降级。
+ - 图表与图示继承页面 token，不另起一套颜色和字号；颜色不能是唯一编码。
+ - 标题、导语、标签、注释和图表文案要经过编辑，不输出模板腔。