md-to-html

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: md-to-html

WHAT

Purpose và context

目的与上下文

Purpose: Markdown → self-contained HTML: Mermaid diagrams, Chart.js, styled tables, code highlight, floating TOC.
Trigger (when to use):
- Render/share
```
.md
```
  as HTML
- Doc has steps, comparisons, numbers to visualize
- Need browser-ready professional output
- Trigger phrases:
```
/md-to-html
```
  ,
```
md2html
```
  ,
```
biến md thành html
```
  ,
```
render md
```
  ,
```
xuất html từ md
```
  ,
```
visualize doc
```
Non-goals: không sửa nội dung file
```
.md
```
nguồn; không ghi HTML cạnh file
```
.md
```
nguồn; không phải site tài liệu nhiều trang có thiết kế riêng (đó là
```
docs-site-macos
```
).

目的： Markdown → 自包含 HTML：Mermaid 图表、Chart.js、样式化表格、代码高亮、浮动 TOC。
触发条件（何时使用）：
- 将
```
.md
```
  渲染或共享为 HTML
- 文档包含步骤、对比或需要可视化的数据
- 需要可直接在浏览器中打开的专业输出
- 触发短语：
```
/md-to-html
```
  、
```
md2html
```
  、
```
biến md thành html
```
  、
```
render md
```
  、
```
xuất html từ md
```
  、
```
visualize doc
```
非目标： 不修改源
```
.md
```
文件的内容；不在源
```
.md
```
文件旁写入 HTML；不用于带自定义设计的多页文档站点（那属于
```
docs-site-macos
```
）。

Mental model

思维模型

file .md → (template đầy đủ ngoài) → HTML standalone (Mermaid · Chart.js · bảng · code highlight · TOC) + output requirements bắt buộc → html/<tên>.html → output report draft

file .md →（外部完整模板）→ 独立 HTML（Mermaid · Chart.js · 表格 · 代码高亮 · TOC）+ 强制输出要求 → html/<ten>.html → 输出报告草稿

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	file `.md` nguồn	có	nội dung cần render
In	Full instructions `~/.gemini/antigravity/skills/md-to-html/SKILL.md`	không	template chi tiết bên ngoài; output requirements dưới đây áp dụng bất kể template
Out	HTML → `html/` dir (e.g. `html/tên-file.html` )	có	NOT same dir as source `.md` ; self-contained
Out	output report `llmwiki/wiki/sources/draft/DDMMYY-<ten>.md` + index + log	có (trừ khi 0 artefact)	mục Delivery

	字段	是否必需？	含义
输入	源 `.md` 文件	是	需要渲染的内容
输入	完整说明 `~/.gemini/antigravity/skills/md-to-html/SKILL.md`	否	外部详细模板；无论是否有模板，下方的输出要求均适用
输出	HTML → `html/` 目录（例如 `html/ten-file.html` ）	是	不得与源 `.md` 位于同一目录；自包含
输出	输出报告 `llmwiki/wiki/sources/draft/DDMMYY-<ten>.md` + 索引 + 日志	是（除非产物数为 0）	用于交付

Rules và capabilities

规则与能力

RULE-01 (MUST): Output HTML →
```
html/
```
dir, NOT same dir as source
```
.md
```
.
RULE-02 (MUST): Output requirements (don't ship a broken page) — the generated HTML must include every item in "Output requirements" below, regardless of the external template.
Capabilities: đọc file Markdown; ghi file HTML tĩnh + draft wiki. Thư viện render (Mermaid, Chart.js) nhúng trong trang.

RULE-01（MUST）：输出 HTML →
```
html/
```
目录，不得与源
```
.md
```
位于同一目录。
RULE-02（MUST）：满足输出要求（不要交付损坏的页面）——无论外部模板如何，生成的 HTML 必须包含下方“输出要求”中的每一项。
能力：读取 Markdown 文件；写入静态 HTML 文件和 wiki 草稿。渲染库（Mermaid、Chart.js）嵌入页面中。

Failure boundaries

失败边界

Không tìm thấy file
```
.md
```
nguồn → blocked, hỏi đường dẫn.
Template ngoài (
```
~/.gemini/...
```
) không có → vẫn render theo Purpose + Output requirements ở đây (không coi là lỗi).
Trang thiếu một mục trong Output requirements → failed, sửa trước khi giao ("don't ship a broken page").

未找到源
```
.md
```
文件 → blocked，询问文件路径。
外部模板（
```
~/.gemini/...
```
）不存在 → 仍根据此处的目的与输出要求进行渲染（不视为错误）。
页面缺少“输出要求”中的某一项 → failed，交付前修复（“不要交付损坏的页面”）。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	đường dẫn `.md`	Đọc file nguồn (+ Full instructions ngoài nếu có)	nội dung	không có file → blocked
W02	judgment	nội dung	Chọn cách visualize: steps/so sánh → Mermaid, số liệu → Chart.js, bảng styled, code highlight, floating TOC	bản dựng HTML	—
W03	deterministic	HTML	Kiểm đủ Output requirements (danh sách dưới)	checklist đủ	thiếu → sửa, lặp W03
W04	effect	HTML	Ghi `html/<tên-file>.html`	file HTML	—
W05	effect	kết quả	Output report draft (mục Delivery)	draft + index + log	0 artefact → skip

Chi tiết từng bước (nguồn chân lý cho W01–W05):

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	确定性	`.md` 路径	读取源文件（若存在，也读取外部完整说明）	内容	没有文件 → blocked
W02	判断	内容	选择可视化方式：步骤/对比 → Mermaid，数据 → Chart.js，样式化表格、代码高亮、浮动 TOC	HTML 草稿	—
W03	确定性	HTML	检查是否满足输出要求（见下方列表）	完整检查清单	缺少项目 → 修复并重复 W03
W04	执行	HTML	写入 `html/<ten-file>.html`	HTML 文件	—
W05	执行	结果	起草输出报告（见“交付”部分）	草稿 + 索引 + 日志	0 个产物 → 跳过

每个步骤的详细信息（W01–W05 的唯一真实来源）：

Output

输出

HTML →

html/

dir (e.g.

html/tên-file.html

). NOT same dir as source

.md

HTML →

html/

目录（例如

html/ten-file.html

）。不得与源

.md

位于同一目录。

Output requirements (don't ship a broken page)

输出要求（不要交付损坏的页面）

The generated HTML must include, regardless of the external template:

<meta charset="utf-8">

<meta name="viewport" content="width=device-width, initial-scale=1">

and a real

<title>

— without viewport the TOC/tables overflow on mobile.

```
:focus-visible{outline:2px solid <accent>;outline-offset:2px}
```
so the floating-TOC links and any buttons show a keyboard focus ring.
```
font-variant-numeric:tabular-nums
```
on
```
table
```
(number columns must not jiggle).
```
@media(prefers-reduced-motion:reduce)
```
to skip Mermaid/Chart entry animation and set
```
scroll-behavior:auto
```
; add
```
html{scroll-behavior:smooth}
```
+
```
scroll-margin-top
```
so TOC anchor jumps glide and headings don't hide under any sticky header.
A favicon (inline data-URI is fine) and
```
alt
```
/
```
<title>
```
on informative diagrams.

无论外部模板如何，生成的 HTML 必须包含：

<meta charset="utf-8">

<meta name="viewport" content="width=device-width, initial-scale=1">

和真实的

<title>

——没有 viewport 时，TOC/表格会在移动端溢出。

```
:focus-visible{outline:2px solid <accent>;outline-offset:2px}
```
，使浮动 TOC 链接及所有按钮显示键盘焦点环。
在
```
table
```
上设置
```
font-variant-numeric:tabular-nums
```
（数字列不得发生位置抖动）。
使用
```
@media(prefers-reduced-motion:reduce)
```
跳过 Mermaid/Chart 入场动画并设置
```
scroll-behavior:auto
```
；添加
```
html{scroll-behavior:smooth}
```
+
```
scroll-margin-top
```
，使 TOC 锚点跳转平滑进行，并避免标题被任何吸顶栏遮挡。
一个 favicon（可使用内联 data URI），并为信息型图表提供
```
alt
```
/
```
<title>
```
。

Full instructions

完整说明

~/.gemini/antigravity/skills/md-to-html/SKILL.md

~/.gemini/antigravity/skills/md-to-html/SKILL.md

Branches

分支

Không có nhánh phụ trong version này.

此版本没有子分支。

Validation và stopping

验证与停止条件

W03 là checklist tất định (grep được trong HTML:

charset

viewport

<title>

:focus-visible

tabular-nums

prefers-reduced-motion

, favicon). Chất lượng visualize (chọn Mermaid hay Chart) cần review mắt. Dừng khi file ở

html/

qua đủ checklist và report đã ghi.

W03 是确定性检查清单（可在 HTML 中通过 grep 检查：

charset

、

viewport

、

<title>

、

:focus-visible

、

tabular-nums

、

prefers-reduced-motion

、favicon）。可视化质量（选择 Mermaid 还是 Chart）需要目视审查。当文件位于

html/

、通过全部检查清单且报告已写入时停止。

Examples

示例

Positive:
```
/md-to-html llmwiki/wiki/concepts/solid-what-how.md
```
→
```
html/solid-what-how.html
```
có TOC nổi, bảng WHAT/HOW styled
```
tabular-nums
```
, viewport + focus ring + reduced-motion; draft
```
DDMMYY-md-to-html-swh.md
```
+ dòng index/log.
Boundary/failure: bản dựng thiếu
```
<meta name="viewport">
```
→ W03 fail (TOC/bảng tràn trên mobile) → thêm rồi mới ghi file; không ghi HTML cạnh file
```
.md
```
nguồn.

正向示例：
```
/md-to-html llmwiki/wiki/concepts/solid-what-how.md
```
→
```
html/solid-what-how.html
```
包含浮动 TOC、使用
```
tabular-nums
```
的样式化 WHAT/HOW 表格、viewport + focus ring + reduced-motion；同时生成草稿
```
DDMMYY-md-to-html-swh.md
```
以及索引/日志行。
边界/失败： 构建结果缺少
```
<meta name="viewport">
```
→ W03 失败（TOC/表格在移动端溢出）→ 添加后才能写入文件；不得在源
```
.md
```
文件旁写入 HTML。

Delivery — Output Report

交付——输出报告

After all main skill tasks complete, write a propose draft to the wiki.

完成所有主要 skill 任务后，向 wiki 写入一份提议草稿。

Steps

步骤

1. Build the filename:

Format:
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= today (e.g.,
```
020626
```
for 2 June 2026)

<ten>

= 2–4 kebab-case words summarising what was done (e.g.,

landing-page-coteccons

brand-kit-fintech

ingest-auth-spec

)

2. Write

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

1. 构建文件名：

格式：
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= 今天（例如，
```
020626
```
表示 2026 年 6 月 2 日）
```
<ten>
```
= 2–4 个概括已完成工作的 kebab-case 单词（例如，
```
landing-page-coteccons
```
、
```
brand-kit-fintech
```
、
```
ingest-auth-spec
```
）

2. 写入

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

Output

Files

File	Action
`path/to/file`	created / modified

File	Action
`path/to/file`	created / modified

Notes

Invoked via:
```
/<skill-name>
```
skill

Invoked via:
```
/<skill-name>
```
skill

Origin

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. 更新 wiki 索引与日志：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当该 skill 产生零个产物和零项决策时跳过（例如，像 `/caveman-stats` 这样的纯显示模式）。