難しい言葉を、読んでいるその場で説明 — popup の使い方

何を作ってくれるのか

読んでいて知らない言葉が 1 つあると、段落全体がわからなくなります。popup はその言葉に小さなカードを付けます。マウスを乗せる(スマートフォンはタップ、キーボードは Tab)とカードが開きます。説明はすべて 1 つの用語集 JSON ファイルにあるので、一度直せばすべてのページが直ります。

ここで試してみてください。このページの点線の付いた言葉(JSON、HTML、CSS など)にマウスを乗せると、SONUB の用語ポップアップが出ます。popup が作るカードもこのような見た目です。

カード 1 枚に入るもの

1. 言葉・読み方・どの分野の言葉か
2. 太字 1 行の意味
3. 2〜3 文の説明
4. かんたんに言うと — 身近なたとえ 1 つ
5. 例 — 1 行に 1 つ、コードとその働き
6. コピーボタン付きのソースコード
7. その場でカードが切り替わる関連用語と、プロジェクトのより詳しいページへの「もっと知る」リンク

インストール

プロジェクトのフォルダーのターミナルで実行してください。すべてのプロジェクトで使うなら -g を付けます。インストールしたら、スキルを読み込むようにエージェントの新しいセッションを始めてください。

ツール popup.py に必要なのは Python 3.8 以上だけです(標準ライブラリのみ使用)。ポップアップ自体はフレームワークもビルド手順もなしに、最新のブラウザーならどこでも動きます。

使い方 — エージェントに頼む

Claude Code では /popup のあとに何を対象にするかを書きます。ほかのエージェントでは「popup スキルで …」と言います。頼む範囲が狭いほど、その部分だけを正確に行います。

エージェントがすること — 7 つのステップ

1. 対象を見つける どのページ・ファイル・部分かを決め、まずプロジェクトにすでにある用語集やツールチップの仕組みを探します。あれば、2 つ目のポップアップの仕組みを足さずに、それを広げます。
2. 最初に一度だけ準備 popup.py init が popup.js と popup.css をコピーし、選んだ言語の空の用語集と設定ファイル .popup.json を作ります。そのあとレイアウトに 2 行を加えます。
3. 点検 popup.py audit が、ドキュメントごとにすでに用語集にある用語と、項目のない候補(略語・camelCase の言葉・コードの言葉)を一覧にします。自分の言語の言葉は検出されないので、エージェントが本文を読んで選びます。
4. 選ぶ 初めての人が立ち止まる言葉、知らないと段落全体がわからなくなる言葉、プロジェクトのあちこちにくり返し出る言葉を選びます。日常語や、本文がその場で説明している言葉は外します。
5. 書く プロジェクトが提供するすべての言語で、確かめた事実だけを書きます。項目は 1 つの入力ファイルにまとめ、popup.py add --dry-run で確認してから取り込みます。既存の項目は --overwrite なしでは上書きしません。
6. 付ける main と article の中のふつうの文章は自動で囲みます。活用形や文は data-term で示し、リンク・カード・見出しの横には ? ボタンを置きます。GitHub で読む Markdown には、代わりに GLOSSARY.md とリンクを付けます。
7. 確かめる popup.py check で用語集を検査し、エージェントがブラウザーでページを開いて、マウスを乗せる・離す・クリック・関連用語・Esc・Tab・狭い画面・別の言語を確かめます。確かめられなかったことは報告に書きます。

ツール popup.py — 自分で実行してもかまいません

popup.py はインストールしたスキルの scripts フォルダーにあります(例：.claude/skills/popup/scripts/popup.py)。下のボックスでは短く popup.py と書いています。パスは git リポジトリのいちばん上にある .popup.json から読みます。

ポップアップ一式をコピーし、用語集(ポップアップのラベルは 17 言語を内蔵)と .popup.json を作る

python3 popup.py init --locales en,ko コピー

ドキュメントが使っている用語と、項目のない専門用語を、使われているファイル数の順に

python3 popup.py audit docs/guide.md コピー

用語を用語集に取り込む — 検査に通らなければ何も書かず、新しいものがなければ “nothing to change” と表示

python3 popup.py add new-terms.json --dry-run コピー

すべての言語、同じ例のコード、関連用語の id、リンク先、ぶつかる表記を検査(エラーなら終了コード 1)

python3 popup.py check コピー

項目を 1 つ表示(見つからなければ似た id を提案)

python3 popup.py show api --locale ko コピー

用語集を Markdown ページ(GLOSSARY.md)として書き出す — 用語ごとにアンカー付き

python3 popup.py md コピー

すべての Markdown ファイルで各用語の最初の出現を GLOSSARY.md にリンクし、短い意味をホバー時のタイトルにする(--write がなければプレビューのみ)

python3 popup.py link docs --write コピー

付けたリンクを外す

python3 popup.py link docs --unlink --write コピー

Web ページに付ける

ビルド手順はありません。ページかレイアウトにこの 2 行を入れれば、popup.js が用語集を読み、本文の用語を見つけます。

<link rel="stylesheet" href="/popup/popup.css">
<script defer src="/popup/popup.js" data-glossary="/popup/glossary.json"></script>

用語集 JSON — 説明はすべてここに

ページには用語の id だけを置き、説明はこの 1 つのファイルに書きます。言語ごとに term・short・long は必須で、easy・example・code・reading は任意です。一度使った id は変えません。

{
  "defaultLocale": "en", "locales": ["en", "ko"],
  "categories": { "web": { "en": "Web", "ko": "웹" } },
  "terms": {
    "api": {
      "category": "web", "aliases": ["API", "APIs"], "related": ["endpoint"], "href": "../docs/api.md",
      "text": {
        "en": { "term": "API", "short": "…", "long": "…", "easy": "…", "example": "`GET /users/42` asks for user 42" },
        "ko": { "term": "API", "reading": "에이피아이", "short": "…", "long": "…" }
      }
    }
  }
}

言葉の示し方

main · article · [data-popup-root]

自動 — これらの範囲のふつうの文章で、各用語の最初の出現を囲みます

<span data-term="api">APIs</span>

活用形や、自動で拾うべきでない語句・文

<button class="popup-info" data-term="api"></button>

リンク・カード・見出しの横の ? ボタン — スマートフォンとキーボード向け

<a href="/docs/api" data-term="api">

リンクに付けると：マウスを 400 ms 止めるとプレビュー、クリックすればそのままリンク先へ

data-popup-scope="shell"

その部分だけ別の意味になる言葉に

PopupGlossary.apply(element)

シングルページアプリが描き直したあと、新しい内容を囲む(二重には囲まない)

React・Vue・Svelte、MkDocs・Docusaurus・VitePress、サーバーのテンプレートやアプリでも使えます。スタックごとの付け方はスキルの references/integrate.md にあります。

GitHub で — README と Markdown

GitHub は JavaScript を実行しないので、Markdown ではポップアップの代わりにリンクを使います。popup.py md が GLOSSARY.md を書き出し、popup.py link がすべてのファイルで各用語の最初の出現をそこにつなぎます。リンクのタイトルが短い意味なので、マウスを乗せると表示されます。コードブロック・見出し・フロントマターはそのままにし、表の中の | は \| に変えて表が崩れないようにします。

Call the [API](../GLOSSARY.md#api "The agreed way one program asks another for something") with an API key.

読む人の使い方

• マウスを乗せるとカードが開き、離すと閉じます。言葉からカードへ移る間は開いたままです。
• クリックするとカードが固定され、コードをコピーしたりリンクを開いたりできます。もう一度クリックすると閉じます。
• 関連用語のチップを押すと、その場でカードが切り替わります。
• Tab で言葉に移ると開き、Enter でカードの中に入り、Esc で閉じるとフォーカスが言葉に戻ります。
• スマートフォン(640 px 以下)では下からせり上がるシートになり、大きな画面の下のほうの言葉ではカードが言葉の上に開きます。
• 右から左に書く言語とダークモードに対応し、韓国語の助詞、アラビア語の接頭辞、中国語や日本語など、文字ごとに合った方法で言葉を見つけます。