Markdown to HTML Report

Default Objectives

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

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

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

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

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

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

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

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

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

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

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

NPX Install

Tags

SKILL.md Content (Chinese)