Article Icons (itshover)
Add tasteful icons to an article using the itshover icon set. itshover publishes 263 icons as shadcn registry components; this skill downloads them and converts each into a clean, static, inline SVG that drops straight into Markdown or HTML — no React, no motion, no build step.
Triggers
Use when the user wants to illustrate a document with icons:
/article-icons <file>
- "给这篇文章配图标", "给文章配图", "add icons to this article", "illustrate with icons"
Inputs
- Target file — the article to illustrate (
.md, .html, .mdx, ...). If not given, ask.
- Style preferences (optional) — color, size, where icons go. Otherwise use sensible defaults below.
The Tool
scripts/fetch_icon.py is the only moving part. It fetches an icon and prints static SVG to stdout.
# Get one icon (defaults: size 24, color currentColor, stroke-width 2)
python3 scripts/fetch_icon.py heart-icon
# Customize
python3 scripts/fetch_icon.py rocket-icon --size 32 --color "#d97757" --stroke-width 1.5
# Discover names (do this FIRST — names must match exactly)
python3 scripts/fetch_icon.py --list
python3 scripts/fetch_icon.py --search arrow
python3 scripts/fetch_icon.py --search brand
scripts/icon_names.json is a cached list of all 263 names for offline reference.
Most icon names end in -icon (e.g. heart-icon, rocket-icon, database-icon), and brands use brand-<name>-icon (e.g. brand-anthropic-icon). But the convention is not universal — real names include shield-check, credit-card, down-chevron, apple-brand-logo, skull-emoji. Never guess a name. Always resolve it with --search first — a wrong guess just wastes a 404.
Workflow
Read the article. Identify its structure: title, section headings (#/##/<h1>/<h2>), key concepts, list groups, callouts/warnings, and any tech/brand mentions (React, GitHub, AI tools...).
Plan the icon map. For each placement, choose a semantically matching icon. Match meaning, not just keywords — a "performance" section → rocket-icon or zap-icon; a "security" section → shield-icon or lock-icon; a warning callout → alert-triangle-icon. Prefer one consistent icon family (all outline, one color) so the article looks designed, not decorated. Resolve every name with --search.
Confirm the plan with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.
Fetch and embed. Run fetch_icon.py for each chosen icon (parallelize independent fetches) and inline the SVG at its placement. See embedding rules below.
Verify. Re-read the edited file; for HTML, open it / screenshot to confirm icons render and align. Report the mapping you applied.
Embedding Rules
HTML — inline the SVG directly. Wrap heading icons so they align with text:
<h2 style="display:flex;align-items:center;gap:.5rem;">
<svg ...>...</svg> Performance
</h2>
Markdown — GitHub-flavored Markdown renders inline HTML, so embed the raw SVG. Keep it on one line and size it small (16–20px) for inline use, 24–28px beside headings:
## <svg ... width="22" height="22" ...>...</svg> Getting Started
If the target renderer strips inline SVG (some strict Markdown engines do), fall back to saving each SVG into an assets/icons/ folder next to the article and referencing it: . Ask which the user prefers if unsure.
Defaults
- Size: 24px beside
h1, 20–22px beside h2/h3, 16px inline in text.
- Color:
currentColor so icons inherit text color. Override with --color only when the user wants accent colors.
- Density: one icon per heading + a few for genuinely key concepts. Do not icon every bullet or sentence — restraint reads as polish.
- Alignment: always
display:flex;align-items:center;gap:.4–.5rem for heading icons in HTML.
Icon Selection Cheatsheet
These names are verified to exist, but the set changes — always reconfirm with --search before fetching.
| Theme |
Real icon names |
| intro / overview |
book-icon, home-icon, globe-icon, map-pin-icon |
| performance / speed |
rocket-icon, gauge-icon, clock-icon |
| security |
shield-check, lock-icon |
| data / charts |
database-family via --search, chart-bar-icon, chart-line-icon, chart-pie-icon, cloud-1-icon |
| settings / config |
gear-icon, sliders-horizontal-icon |
| warning / note |
triangle-alert-icon, info-circle-icon, filled-bell-icon |
| success / done |
checked-icon, double-check-icon, simple-checked-icon |
| ideas |
brain-circuit-icon, sparkles-icon, star-icon, bulb-svg |
| AI / brands |
brand-anthropic-icon, brand-gemini-icon, ... (--search brand) |
| navigation |
arrow-narrow-*-icon, down-chevron, right-chevron |
Edge Cases
| Scenario |
Handling |
| Icon name not found (404) |
Run --search <term>; pick the closest real name. Never invent names. |
| Icon won't convert (rare; ~2/263 use a JS map for paths) |
Script prints a clear error. Pick an alternative icon with similar meaning. |
| No network access |
Cannot fetch SVGs; tell the user the skill needs network access to itshover.com. |
| Markdown renderer strips inline SVG |
Fall back to assets/icons/*.svg + image references. |
| Article already has icons |
Ask whether to replace, supplement, or skip those sections. |
| Very long article |
Confirm the mapping for the first few sections, then apply the same family consistently throughout. |
Checklist
Before finishing:
1---
2name: article-icons
3description: "Illustrate an article (Markdown, HTML, etc.) with animated-style icons from itshover.com/icons. Fetches icons as clean inline SVG and places them at section headings, key concepts, lists, and callouts. Triggers on: /article-icons, 配图, 给文章配图标, add icons to article, illustrate with icons."
4user-invocable: true
5metadata:
6 source: https://skillmd.com/skills/smallnest/article-icons
7---
8
9# Article Icons (itshover)
10
11Add tasteful icons to an article using the [itshover](https://www.itshover.com/icons) icon set. itshover publishes 263 icons as shadcn registry components; this skill downloads them and converts each into a clean, static, inline **SVG** that drops straight into Markdown or HTML — no React, no `motion`, no build step.
12
13## Triggers
14
15Use when the user wants to illustrate a document with icons:
16- `/article-icons <file>`
17- "给这篇文章配图标", "给文章配图", "add icons to this article", "illustrate with icons"
18
19## Inputs
20
21- **Target file** — the article to illustrate (`.md`, `.html`, `.mdx`, ...). If not given, ask.
22- **Style preferences** (optional) — color, size, where icons go. Otherwise use sensible defaults below.
23
24## The Tool
25
26`scripts/fetch_icon.py` is the only moving part. It fetches an icon and prints static SVG to stdout.
27
28```bash
29# Get one icon (defaults: size 24, color currentColor, stroke-width 2)
30python3 scripts/fetch_icon.py heart-icon
31
32# Customize
33python3 scripts/fetch_icon.py rocket-icon --size 32 --color "#d97757" --stroke-width 1.5
34
35# Discover names (do this FIRST — names must match exactly)
36python3 scripts/fetch_icon.py --list
37python3 scripts/fetch_icon.py --search arrow
38python3 scripts/fetch_icon.py --search brand
39```
40
41`scripts/icon_names.json` is a cached list of all 263 names for offline reference.
42
43Most icon names end in `-icon` (e.g. `heart-icon`, `rocket-icon`, `database-icon`), and brands use `brand-<name>-icon` (e.g. `brand-anthropic-icon`). But the convention is **not** universal — real names include `shield-check`, `credit-card`, `down-chevron`, `apple-brand-logo`, `skull-emoji`. **Never guess a name. Always resolve it with `--search` first** — a wrong guess just wastes a 404.
44
45## Workflow
46
471. **Read the article.** Identify its structure: title, section headings (`#`/`##`/`<h1>`/`<h2>`), key concepts, list groups, callouts/warnings, and any tech/brand mentions (React, GitHub, AI tools...).
48
492. **Plan the icon map.** For each placement, choose a semantically matching icon. Match meaning, not just keywords — a "performance" section → `rocket-icon` or `zap-icon`; a "security" section → `shield-icon` or `lock-icon`; a warning callout → `alert-triangle-icon`. Prefer **one consistent icon family** (all outline, one color) so the article looks designed, not decorated. Resolve every name with `--search`.
50
513. **Confirm the plan** with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.
52
534. **Fetch and embed.** Run `fetch_icon.py` for each chosen icon (parallelize independent fetches) and inline the SVG at its placement. See embedding rules below.
54
555. **Verify.** Re-read the edited file; for HTML, open it / screenshot to confirm icons render and align. Report the mapping you applied.
56
57## Embedding Rules
58
59**HTML** — inline the SVG directly. Wrap heading icons so they align with text:
60
61```html
62<h2 style="display:flex;align-items:center;gap:.5rem;">
63 <svg ...>...</svg> Performance
64</h2>
65```
66
67**Markdown** — GitHub-flavored Markdown renders inline HTML, so embed the raw SVG. Keep it on one line and size it small (16–20px) for inline use, 24–28px beside headings:
68
69```markdown
70## <svg ... width="22" height="22" ...>...</svg> Getting Started
71```
72
73If the target renderer strips inline SVG (some strict Markdown engines do), fall back to saving each SVG into an `assets/icons/` folder next to the article and referencing it: ``. Ask which the user prefers if unsure.
74
75### Defaults
76- **Size:** 24px beside `h1`, 20–22px beside `h2`/`h3`, 16px inline in text.
77- **Color:** `currentColor` so icons inherit text color. Override with `--color` only when the user wants accent colors.
78- **Density:** one icon per heading + a few for genuinely key concepts. Do **not** icon every bullet or sentence — restraint reads as polish.
79- **Alignment:** always `display:flex;align-items:center;gap:.4–.5rem` for heading icons in HTML.
80
81## Icon Selection Cheatsheet
82
83These names are verified to exist, but the set changes — always reconfirm with `--search` before fetching.
84
85| Theme | Real icon names |
86|-------|------|
87| intro / overview | `book-icon`, `home-icon`, `globe-icon`, `map-pin-icon` |
88| performance / speed | `rocket-icon`, `gauge-icon`, `clock-icon` |
89| security | `shield-check`, `lock-icon` |
90| data / charts | `database`-family via `--search`, `chart-bar-icon`, `chart-line-icon`, `chart-pie-icon`, `cloud-1-icon` |
91| settings / config | `gear-icon`, `sliders-horizontal-icon` |
92| warning / note | `triangle-alert-icon`, `info-circle-icon`, `filled-bell-icon` |
93| success / done | `checked-icon`, `double-check-icon`, `simple-checked-icon` |
94| ideas | `brain-circuit-icon`, `sparkles-icon`, `star-icon`, `bulb-svg` |
95| AI / brands | `brand-anthropic-icon`, `brand-gemini-icon`, ... (`--search brand`) |
96| navigation | `arrow-narrow-*-icon`, `down-chevron`, `right-chevron` |
97
98## Edge Cases
99
100| Scenario | Handling |
101|----------|----------|
102| Icon name not found (404) | Run `--search <term>`; pick the closest real name. Never invent names. |
103| Icon won't convert (rare; ~2/263 use a JS map for paths) | Script prints a clear error. Pick an alternative icon with similar meaning. |
104| No network access | Cannot fetch SVGs; tell the user the skill needs network access to itshover.com. |
105| Markdown renderer strips inline SVG | Fall back to `assets/icons/*.svg` + image references. |
106| Article already has icons | Ask whether to replace, supplement, or skip those sections. |
107| Very long article | Confirm the mapping for the first few sections, then apply the same family consistently throughout. |
108
109## Checklist
110
111Before finishing:
112- [ ] Every icon name was resolved with `--search`/`--list` (no guessed names)
113- [ ] One consistent icon family/color across the article
114- [ ] Icons placed at headings + genuinely key points, not everywhere
115- [ ] Heading icons vertically aligned with text (flex + gap)
116- [ ] Edited file re-read; HTML visually verified to render
117- [ ] Mapping summary reported to the user