article-icons

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

1. 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...).

2. 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.

3. Confirm the plan with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.

4. 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.

5. 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: ![](assets/icons/rocket-icon.svg). 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:

• Every icon name was resolved with --search/--list (no guessed names)
• One consistent icon family/color across the article
• Icons placed at headings + genuinely key points, not everywhere
• Heading icons vertically aligned with text (flex + gap)
• Edited file re-read; HTML visually verified to render
• Mapping summary reported to the user