html-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML document

HTML文档

Turn one complete Markdown PRD or technical design into one verified static HTML page. Keep Markdown canonical. Change presentation, not meaning.

将一份完整的Markdown格式PRD或技术设计文档转换为经过验证的静态HTML页面。保留Markdown的标准格式，仅调整呈现方式，不改变内容含义。

Boundaries

边界限制

Accept an existing Markdown file or exact inline Markdown.
Support only
```
prd
```
and
```
design
```
document kinds.
Infer the kind only from the exact basename
```
prd.md
```
or
```
design.md
```
. Otherwise require the user or request to name it.
Do not write requirements, settle design choices, summarize missing content, or edit the source.
If the source is only a rough brief, use the appropriate authoring skill first.
Do not hand-edit generated HTML. Change the template or renderer, then regenerate.
Do not publish or host the result unless the user separately asks.

接收现有的Markdown文件或精确的内联Markdown内容。
仅支持
```
prd
```
和
```
design
```
两种文档类型。
仅能通过精确的文件名
```
prd.md
```
或
```
design.md
```
推断文档类型，否则需要用户明确指定。
不编写需求、确定设计方案、补充缺失内容或编辑源文档。
如果源内容只是粗略的大纲，请先使用对应的文档创作工具。
不要手动编辑生成的HTML，应修改模板或渲染器后重新生成。
除非用户单独要求，否则不要发布或托管生成的结果。

Requirements

环境要求

Generation requires Python 3.11 or newer, Pandoc 3 or newer, Node.js 22.12 or newer, and npm. The skill directory contains a locked Mermaid dependency tree.

Before the first Mermaid render, run:

bash

npm ci --prefix <skill-directory>

Use

scripts/html_doc.py

from this skill directory for all generation and lifecycle operations.

生成HTML需要Python 3.11或更高版本、Pandoc 3或更高版本、Node.js 22.12或更高版本以及npm。本工具目录中包含锁定版本的Mermaid依赖树。

首次渲染Mermaid图表前，请运行：

bash

npm ci --prefix <skill-directory>

使用本工具目录中的

scripts/html_doc.py

完成所有生成及生命周期操作。

Workflow

工作流程

1. Read and classify the source

1. 读取并分类源文档

Read the complete source. Confirm it is no larger than 2 MiB. Determine the document kind from the request or the exact basename rule.

Treat content problems separately from presentation problems. If the Markdown contradicts itself, omits a required decision, or contains an invalid diagram, report that source problem. Do not silently repair its meaning.

读取完整的源文档，确认其大小不超过2 MiB。根据用户请求或文件名规则确定文档类型。

将内容问题与呈现问题分开处理。如果Markdown内容存在自相矛盾、遗漏必要决策或包含无效图表的情况，需报告源文档问题，不得擅自修改其含义。

2. Create a candidate

2. 生成候选版本

For a file source:

bash

python3 <skill-directory>/scripts/html_doc.py render <source.md> --kind <prd-or-design> --out <output.html>

--kind

may be omitted only for exact

prd.md

and

design.md

basenames.

--out

may be omitted to create a sibling HTML file.

For exact inline Markdown, pipe it through standard input and provide both kind and output:

bash

python3 <skill-directory>/scripts/html_doc.py render --inline --kind <prd-or-design> --out <output.html>

The command returns JSON containing

candidate

output

, and

token

. It does not replace the final output. Keep those exact values for verification and finalization.

If an output lock already exists, do not delete it automatically. It may represent another pending render. Report its path. Use

discard --force-stale

only when the state is known to be abandoned.

针对文件源：

bash

python3 <skill-directory>/scripts/html_doc.py render <source.md> --kind <prd-or-design> --out <output.html>

仅当文件名为精确的

prd.md

或

design.md

时，可省略

--kind

参数。省略

--out

参数将在源文件同级目录生成HTML文件。

针对精确的内联Markdown内容，通过标准输入传递，并指定文档类型和输出路径：

bash

python3 <skill-directory>/scripts/html_doc.py render --inline --kind <prd-or-design> --out <output.html>

该命令返回包含

candidate

、

output

和

token

的JSON数据，不会直接替换最终输出文件，请保留这些值用于验证和定稿。

如果已存在输出锁文件，请勿自动删除，它可能代表另一个待处理的渲染任务。需报告锁文件路径，仅当确认状态已废弃时，才可使用

discard --force-stale

命令。

3. Verify the candidate in a real browser

3. 在真实浏览器中验证候选版本

Open the candidate as a local file. Do not treat source inspection as browser proof.

Check all of these:

desktop at 1440 CSS pixels;
tablet at 768 CSS pixels;
mobile at 390 CSS pixels;
A4 and US Letter print preview;
table-of-contents links and section targets;
keyboard order from skip link through navigation and document links;
visible focus indicators;
one
```
main
```
landmark and a sensible heading outline;
unique DOM IDs;
horizontal overflow, clipped text, code, tables, and diagrams;
useful diagram alternatives and accessible disclosure controls;
console errors and failed resource requests;
operation with browser network access disabled.

Compare the canonical content inside

main

with the Markdown abstract syntax tree. Navigation, source metadata, and derived accessibility text are not canonical content. Each top-level source block must map to one ordered

data-source-block

node with its SHA-256 identity and nested content intact. A Mermaid block maps to one figure whose exact source appears once in its disclosure.

If a presentation defect comes from the shared renderer or styles, fix that source and regenerate. If it is a content defect, leave the source and candidate unchanged and report it.

将候选版本作为本地文件打开，仅检查源文档无法替代浏览器验证。

需检查以下所有项：

桌面端（1440 CSS像素）；
平板端（768 CSS像素）；
移动端（390 CSS像素）；
A4和US Letter纸张的打印预览；
目录链接和章节跳转目标；
从跳过链接到导航及文档链接的键盘导航顺序；
可见的焦点指示器；
一个
```
main
```
地标元素和合理的标题层级；
唯一的DOM ID；
横向溢出、文本截断、代码、表格及图表的显示情况；
实用的图表替代方案和可访问的展开/收起控件；
控制台错误和资源请求失败情况；
禁用浏览器网络访问时的运行状态。

将

main

元素内的标准内容与Markdown抽象语法树进行对比。导航栏、源元数据及衍生的无障碍文本不属于标准内容。每个顶级源块必须映射到一个有序的

data-source-block

节点，且其SHA-256标识和嵌套内容保持完整。Mermaid块需映射到一个figure元素，其精确源内容需在展开控件中保留一份副本。

如果呈现缺陷来自共享渲染器或样式，需修复源文件后重新生成；如果是内容缺陷，需保留源文档和候选版本不变并报告问题。

4. Finalize or discard

4. 定稿或丢弃候选版本

Only after every check passes, atomically install the candidate:

bash

python3 <skill-directory>/scripts/html_doc.py finalize --out <output.html> --token <token>

If any check fails, remove only this pending candidate:

bash

python3 <skill-directory>/scripts/html_doc.py discard --out <output.html> --token <token>

Finalization performs one same-directory atomic replacement. It never deletes the previous output first. A failed render, check, or replacement must leave the previous verified output byte-for-byte unchanged.

仅当所有检查通过后，以原子方式安装候选版本：

bash

python3 <skill-directory>/scripts/html_doc.py finalize --out <output.html> --token <token>

如果任何检查失败，仅删除当前待处理的候选版本：

bash

python3 <skill-directory>/scripts/html_doc.py discard --out <output.html> --token <token>

定稿操作会在同一目录下进行原子替换，不会先删除之前的输出文件。渲染、检查或替换失败时，必须保证之前已验证的输出文件完全不变。

Output standard

输出标准

The final page must:

preserve source wording and order;
use canonical
```
prd
```
or
```
design
```
machine metadata;
record the source path and SHA-256 hash;
use semantic HTML, inline CSS, and no runtime JavaScript;
contain no external runtime assets;
use a restrained blue-grey visual system;
remain readable without color, a mouse, a wide screen, or network access;
include responsive and print styles;
embed validated Mermaid SVG as a base64 image and retain the exact source in a disclosure.

Stop when the verified candidate is finalized. Report the output path, source hash, and browser checks performed.

最终页面必须满足：

保留源文档的措辞和顺序；
使用标准的
```
prd
```
或
```
design
```
机器元数据；
记录源文件路径和SHA-256哈希值；
使用语义化HTML、内联CSS，无运行时JavaScript；
不包含外部运行时资源；
使用简约的蓝灰色视觉系统；
在无颜色、无鼠标、窄屏或无网络访问的情况下仍可读；
包含响应式样式和打印样式；
将验证后的Mermaid SVG作为base64图片嵌入，并在展开控件中保留精确的源内容。

当验证后的候选版本定稿后，流程结束。需报告输出文件路径、源文件哈希值及已执行的浏览器检查项。