1 line
5.7 KiB
JSON
1 line
5.7 KiB
JSON
{"repo": "adaminspaceship/html-explainer", "files": {"README.md": {"765f1e3d60807683eed8d29ad563f31b1831166d": {"t": 1785846892.6200402, "n": 5391, "h": "c267dad09c14c74f", "c": "<p align=\"center\">\n <img src=\"./headline.png\" alt=\"html-explainer\" />\n</p>\n\n# html-explainer\n\nA Claude Code skill that turns substantive explanations, comparisons, walkthroughs, and reports into **fun, editorial, single-file HTML artifacts** instead of walls of markdown — with a built-in *highlight-to-explain* widget powered by an LLM.\n\nInspired by [The unreasonable effectiveness of HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html).\n\n---\n\n## What it looks like\n\nWarm cream background, deep ink text, **Instrument Serif** display headlines, **Inter** body, **Caveat** marginalia, coral/butter/sky accents. Less \"SaaS dashboard,\" more *Quanta Magazine* or a Stripe Press book page.\n\nEvery generated artifact ships with:\n\n- **Mermaid** flowcharts, sequence, state, ERD, mindmap — declarative diagrams\n- **rough-notation** hand-drawn underlines, circles, highlights on prose\n- **Alpine.js** for tabs / toggles / copy buttons without a build step\n- **Lucide** icons\n- **Lottie** animations (`<lottie-player>`) — embed free animations from lottiefiles.com sparingly\n- **Drawflow** (optional) for React Flow–style interactive node graphs\n- **Highlight-to-Explain widget**: select any text → ✦ Explain → an LLM streams an inline, context-aware explanation into a popover anchored to your selection\n\nAll single-file, all CDN, zero build step.\n\n## Install\n\n```bash\ngit clone https://github.com/adaminspaceship/html-explainer.git ~/.claude/skills/html-explainer\n```\n\nThat's it. Restart Claude Code (or start a new session) and the skill will be auto-discovered.\n\n## Use\n\nJust talk to Claude normally. The skill auto-fires on requests like:\n\n- *\"explain how React Fiber works\"*\n- *\"walk me through OAuth\"*\n- *\"compare Postgres and SQLite for this use case\"*\n- *\"diagram the auth flow\"*\n- *\"break down what just happened in this PR\"*\n- *\"make me a cheatsheet for git rebase\"*\n\nClaude will copy the template, edit only the content sections, save the file in your current working directory, and `open` it in the browser.\n\n## The Highlight-to-Explain widget\n\nEvery artifact has it built in. The flow:\n\n1. Highlight any phrase in the rendered HTML\n2. A small `✦ Explain` pill appears above the selection\n3. Click — an LLM streams a 2-4 sentence explanation into a popover anchored below\n4. The LLM gets **rich context**: document title, subtitle, nearest section heading, and the containing paragraph — so explanations are grounded in the document, not generic dictionary answers\n\n### Configuration\n\n- **Provider**: Google Gemini API (browser-direct, `streamGenerateContent?alt=sse`)\n- **Text model** (selection explanation): `gemini-3.1-flash-lite`\n- **Image model** (baked illustrations): `gemini-3.1-flash-image`\n- **API key**: a single Gemini API key (`AIza…`) handles both. Prompted once on first interaction; stored only in your browser's `localStorage` under `html-explain-gemini-key`. Sent only to `generativelanguage.googleapis.com`. Get one free at https://aistudio.google.com/apikey. The popover has a `⚙ reset key` button.\n\nTo swap models, edit the `TEXT_MODEL` / `IMAGE_MODEL` constants at the top of the widget script in `base.html`.\n\n## What's in the box\n\n```\nhtml-explainer/\n├── SKILL.md # Trigger description and authoring instructions for Claude\n├── base.html # The canonical template — all generated artifacts start from this\n├── example.html # A worked explainer demonstrating every library + the widget\n├── README.md # This file\n└── LICENSE\n```\n\n## Customizing the aesthetic\n\n`base.html` is the single source of truth for the look. Edit it to your taste:\n\n- **Palette**: `tailwind.config` → `theme.extend.colors` (cream, ink, coral, butter, plum, sky, blush)\n- **Fonts**: change the Google Fonts URL + the `fontFamily` map\n- **Background gradient**: the `body::before` rule (paper-grain coral + sky radials)\n- **Mermaid theme**: the `mermaid.initialize` call at the bottom of `<body>`\n- **Widget models**: `const TEXT_MODEL = 'gemini-3.1-flash-lite'` and `const IMAGE_MODEL = 'gemini-3.1-flash-image'` at the top of the widget script\n\nAll future artifacts inherit your changes automatically (they copy from `base.html`).\n\n## Why HTML\n\nMarkdown was built for *reading*. HTML was built for *staying in the loop* — comparison grids, diagrams that move, sliders, tabs you can flip between, hand-drawn annotations on key phrases. Past ~100 lines, markdown collapses into a wall; HTML keeps shape.\n\n> \"The real reason I use HTML instead of Markdown is that it helps me feel much more in the loop with Claude.\" — [the article](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html)\n\n## Stack\n\n- [Tailwind CSS](https://tailwindcss.com) (Play CDN — utilities only, no DaisyUI)\n- [Instrument Serif](https://fonts.google.com/specimen/Instrument+Serif), [Inter](https://rsms.me/inter/), [JetBrains Mono](https://www.jetbrains.com/lp/mono/), [Caveat](https://fonts.google.com/specimen/Caveat)\n- [Mermaid](https://mermaid.js.org/) — diagrams\n- [rough-notation](https://roughnotation.com/) — hand-drawn annotations\n- [Alpine.js](https://alpinejs.dev/) — sprinkles of reactivity\n- [Lucide](https://lucide.dev/) — icons\n- [Drawflow](https://github.com/jerosoler/Drawflow) (optional) — React Flow–style node editor\n- [Chart.js](https://www.chartjs.org/) (optional) — charts\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n"}}}} |