YAML to HTML Explainer

yaml-to-html explainer

A Claude Code plugin with two skills that turn an understanding target — a document, repository summary, pull request / diff, README, design note, or specification — into an offline HTML explainer bundle tailored to how a particular reader understands things.

The two skills split the work cleanly:

skill	role	output
generate-explainer-yaml	Gen YAML	core.yaml (meaning) + view.yaml (presentation strategy)
generate-explainer-html	Gen HTML	a bundle: a light/dark shell + switchable iframe views

Input (doc / repo / PR / README / design note / spec)
  ↓ generate-explainer-yaml
core.yaml  (what it MEANS — concepts, relations, importance, difficulty, sources)
view.yaml  (how to SHOW it to this reader — audience, forms, emphasis)
  ↓ generate-explainer-html
HTML bundle: index.html (light/dark shell + view switcher + add-a-view prompts)
             + views/NN-<id>.html  (one switchable iframe view each)

Quick start

1. Install the plugin (run these inside Claude Code):

/plugin marketplace add hirokita117/yaml-to-html-skill
/plugin install yaml-to-html@yaml-to-html-skill

2. Ask for an explainer. A single prompt runs both skills in the right order — generate-explainer-yaml first (writes core.yaml + view.yaml), then generate-explainer-html (reads that YAML by absolute path and builds the HTML bundle). Paste a document / repo summary / PR diff / README / design note, or point at a path.

English

Build me an offline HTML explainer bundle for this PR, aimed at an engineer reviewing it.
First use generate-explainer-yaml to produce core.yaml + view.yaml, then use
generate-explainer-html to turn that YAML (by absolute path) into a light/dark switchable
view bundle in ./explainer-bundle.

--- target ---
<paste the PR / document / repo summary / README / design note here, or give a path>

Japanese

この PR を、レビューするエンジニア向けに分かりやすく説明する HTML バンドルを作ってください。
まず generate-explainer-yaml で core.yaml と view.yaml を生成し、
続けて generate-explainer-html でその YAML（絶対パス）から
ライト/ダーク切り替え付きのビュー HTML バンドルを ./explainer-bundle に組み立ててください。

--- 対象 ---
<ここに PR / ドキュメント / リポジトリ概要 / README / 設計メモを貼る、またはパスを指定>

3. Open it. Open ./explainer-bundle/index.html in Firefox over file://, or serve the folder for Chrome/Edge (cd explainer-bundle && python3 -m http.server). See Opening the bundle for why.

Prefer to drive it step by step? Generate just the YAML first ("generate-explainer-yaml で core.yaml と view.yaml を作って"), review the two files, then hand their absolute paths to generate-explainer-html.

What the output looks like

The HTML output is a bundle (a directory), not a single file:

• A light/dark shell (index.html) with a theme toggle (light by default).
• A right pane that switches between iframe views. Each view is a separate self-contained HTML document under views/. Views are additive — ask for a "table" view next to your "beginner" view and you get a second tab, not a replacement.
• A left pane of copyable prompt templates. Each asks another local-file-reading AI (Claude Code / Cursor / an agentic IDE) to read the YAML by absolute path and return one new view to add to the bundle. The prompts never embed the YAML content.

This is not a web app

• No server, no API route, no build pipeline, no chat UI.
• No external CDN, CSS, or JS; no network calls; no storage or cookies.
• Each view runs in a sandboxed iframe (sandbox="allow-scripts", no allow-same-origin) and cannot reach the parent page.

The shell loads each view via a local relative src (e.g. views/01-engineer.html) — a local file read, not a network read. (A remote src stays forbidden.)

core.yaml vs. view.yaml

Two intermediate representations sit between the input and the HTML, produced by generate-explainer-yaml:

	core.yaml	view.yaml
answers	what the target means	how to show it to this reader
depends on the reader?	no	yes
contents	concepts, relations, importance, difficulty, confidence, questions, risks, source refs	audience, preferred/avoided forms, density, tone, emphasis, generation policy
schema	generate-explainer-yaml/references/core-yaml-schema.md	generate-explainer-yaml/references/view-yaml-schema.md

Keeping meaning separate from presentation is what lets the same core.yaml become many switchable views — each a different form of the same meaning.