sn-md-to-html-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown 转 HTML 报告

Markdown to HTML Report

默认目标

Default Objectives

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

Generate HTML for "long-form research report reading version": with spacious body text, naturally inserted images, clear tables, usable directory, and offline accessibility. Prioritize content credibility and reading comfort; avoid marketing pages or overly flashy pages.

Recommended Workflow

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

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，这是正常的。

Prioritize using built-in scripts to generate stable results:

bash

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

Common parameters:

```
--embed-images
```
: Embed local images into HTML, suitable for single-file sharing. Enabled by default.
```
--no-embed-images
```
: Keep relative image paths, suitable for folder-wide publication.
```
--with-js
```
: Add lightweight interactions such as reading progress, directory highlighting, and back-to-top button.
```
--keep-inline-toc
```
: Keep the existing directory in the Markdown body; by default, the body directory is removed to avoid duplication with the sidebar directory.
```
--mermaid-source auto|cdn|local|none
```
: Render Mermaid code blocks in Markdown. Default is
```
auto
```
, uses CDN when ```mermaid code blocks are detected;
```
local
```
references
```
mermaid.min.js
```
in the same directory as the output HTML;
```
none
```
keeps it as a regular code block.
```
--title-style comfortable
```
: Default comfortable report template.

Run image check after generation:

bash

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

When using

--embed-images

for output, it is normal for the number of local image references in the check result to be 0.

工作流程

Workflow

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

Determine input Markdown and output HTML.
- When only the input path is provided by the user, generate a same-named
```
.html
```
  file in the same directory.
- If a same-named HTML already exists, prefer to use a new file name unless the user explicitly requests overwriting.
Check Markdown before conversion.
- Use the directory where the Markdown is located as the base for relative image paths.
- Correct misused full-width table vertical lines
```
｜
```
  to half-width
```
|
```
  to avoid table misalignment.
- Add blank lines before lists starting with
```
-
```
  ,
```
*
```
  or numbered lists that follow "explanatory text:" without a blank line, so that the bullet points are rendered as actual lists.
- If the Markdown already has
```
## 目录
```
  (Table of Contents) with chapter anchor lists, it is removed from the body by default; the sidebar directory already provides navigation, and the body directory would take up redundant space.
- Keep the original content, do not summarize, rewrite, or add new facts.
Generate complete HTML5.
- CSS is inlined into
```
<style>
```
  , no dependencies on CDN, online fonts, or external CSS.
- No JavaScript is required by default; only add a small amount of native JS when the user wants reading progress, directory highlighting, or back-to-top functionality.
- ```mermaid code blocks in Markdown are converted to Mermaid chart containers; for fully offline sharing, use
```
  --mermaid-source local
```
and place
```
  mermaid.min.js
```
in the same directory as the output HTML.
- Images are embedded as
```
data:image/...
```
  by default, allowing the HTML single file to be opened independently.
Self-check the output.
- Check if the number of titles, directories, tables, and images is roughly consistent with the source document.
- Check that wide tables can scroll horizontally on mobile devices, and images do not break the page layout.
- Check HTML attributes, closed tags, directory anchors, and CSS syntax.

视觉原则

Visual Principles

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

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

Default preferences derived from this effect:

The page should look like a "clean research report", not a backend table page or a marketing landing page.
Use a light gray page background and white body paper area, with clear boundaries for the body but not overly card-style.
On desktop, use a sticky directory on the left and the body on the right; on mobile, place the directory above the body or make it collapsible.
Existing Markdown directories in the body are not kept by default unless the user explicitly needs a body directory or uses
```
--keep-inline-toc
```
.
H1 can use a restrained blue-green gradient title area, while body titles maintain clear hierarchy.
Comfortable white space in the body: sufficient pauses between paragraphs, tables, and images for readers.
Images appear naturally as chart nodes: centered, maximum width 100%, light border, light shadow, and sufficient spacing with context.
Tables suitable for research report scanning: header can be light or dark, but must be stable, horizontally scrollable, and have sufficient cell padding.
Avoid filling the page with a single dark blue/purple color; recommend blue-green main color with a small amount of blue links.

舒适模板要点

Comfort Template Key Points

默认 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)

。

The default CSS should be close to the following parameters, and can be adjusted slightly according to content:

```
body
```
:
```
line-height: 1.75
```
, light gray background, system Chinese fonts.

.layout

: On desktop,

grid-template-columns: minmax(220px, 280px) minmax(0, 1fr)

, maximum width around

1480px

, page margin around

28px

```
.toc-panel
```
: Sticky, semi-transparent white background, thin border, light shadow; directory item font size around
```
13px
```
.
```
main
```
: White body container,
```
8px
```
border-radius, thin border, light shadow.
```
article
```
: On desktop, padding around
```
46px min(6vw, 76px) 68px
```
.

h1

: Title area can use

linear-gradient(135deg, #0f766e, #155e75, #1d4ed8)

, font size

clamp(30px, 4vw, 52px)

```
h2
```
: Sufficient space above, thin top divider, font size
```
clamp(22px, 2.3vw, 30px)
```
.
```
h3
```
: Font size around
```
21px
```
, darker color than body text.
```
blockquote
```
: Use light blue-green background and left emphasis line, can carry captions or annotations.
```
.table-scroll
```
: As the outer scroll container for tables,
```
width:100%
```
,
```
overflow-x:auto
```
, thin border and border-radius.
```
table
```
: Keep native
```
display:table
```
and
```
width:100%
```
, do not use
```
display:block
```
; short tables should naturally fill the body width, wide tables are scrolled horizontally by
```
.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)

图片规则

Image Rules

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

Embed local images by default, suitable for sending a single HTML file to others.
Use
```
--no-embed-images
```
to keep relative paths when the user requires smaller file size, replaceable images, or an existing publication directory.
Do not write absolute local paths into HTML unless explicitly requested by the user.
If the reference block after a Markdown image is clearly a caption, keep it as an under-image description or blockquote without changing the text.
Missing images should be explained with their paths in the final response.

表格规则

Table Rules

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

Fix full-width vertical lines
```
｜
```
.
Fix the issue where Markdown bullet points are not rendered due to missing blank lines before lists; do not modify content in code blocks.
Use a Markdown parser or structured conversion, do not use fragile string concatenation to build HTML tables.
Wide tables must be horizontally scrollable, cannot squeeze the body, and cannot break the page layout on mobile devices.
Short tables should not leave large blank spaces on the right; table elements should keep
```
width:100%
```
, and scrolling is only placed in the outer container.
Do not delete columns, merge columns, or rewrite cell content for beautification purposes.

交互规则

Interaction Rules

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

--with-js

：

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

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

Static HTML is sufficient by default. Only add

--with-js

when the user requests "more convenient navigation", "progress bar like the original report", or when the document is particularly long:

Reading progress bar.
Current directory item highlighting.
Back-to-top button.
Mobile directory expand/collapse.

All interactions use native JavaScript, no dependencies on external libraries; scripts should check for element existence first.

打印规则

Print Rules

添加

@media print

：

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

Add

@media print

Hide auxiliary UI such as directories, progress bars, and back-to-top buttons.
Change page background to white, remove shadows.
Try to avoid unnatural truncation of tables, images, and blockquotes.
Titles do not rely on dark gradient backgrounds when printing.

质量自检

Quality Self-Check

生成后至少确认：

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

At least confirm the following after generation:

The HTML file exists and is readable.
The number of
```
<table>
```
and
```
<img>
```
elements is roughly consistent with the source document.
Bullet point content should be rendered as
```
<ul>/<ol>
```
and
```
<li>
```
, not kept as regular paragraphs with hyphens.
Tables should be wrapped by
```
.table-scroll
```
, and
```
table
```
itself should not use
```
display:block
```
.
Embedded images include
```
data:image/
```
; when not embedded,
```
check_image_refs.py
```
shows no missing images.
All directory links are
```
href="#..."
```
and the target ID exists.
The body should not contain both an original Markdown directory and a sidebar directory unless explicitly requested by the user.
No broken tags, empty
```
href
```
, duplicate obvious IDs, invalid
```
calc()
```
, or damaged CSS.

最终回复

Final Response

简洁说明：

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

Brief explanation:

Output HTML path.
Whether images are embedded, or the result of image reference check.
Fixed formatting issues, such as full-width table vertical lines.
Uncompleted verifications, if any.

sn-md-to-html-report

Original

Translation

Markdown 转 HTML 报告

Markdown to HTML Report

默认目标

Default Objectives

推荐路径

Recommended Workflow

工作流程

Workflow

视觉原则

Visual Principles

舒适模板要点

Comfort Template Key Points

图片规则

Image Rules

表格规则

Table Rules

交互规则

Interaction Rules

打印规则

Print Rules

质量自检

Quality Self-Check

最终回复

Final Response