# Astroの記事リンクにリンク先のブランドアイコンを付ける — rehypeプラグインと3つの落とし穴 > GitHub・MDN・Vercelなどへのリンクに、simple-iconsのブランドマークをインラインSVGのスプライトとして付けるAstroのビルド時rehypeプラグイン。厳しいCSPのもとでも動作します。 - Source: https://oharu121.com/ja/blog/astro-rehype-plugin-link-brand-icons-svg-sprite-csp/ - Published: 2026-10-16T22:57:40+09:00 - Tags: Astro, CSS, SVG, スプライト, CSP --- ## はじめに GitHubはプルリクエストへのリンクを、プルリクエストのアイコンとタイトル、番号で表示します。Confluenceも、貼り付けたリンクをリンク先ページの小さなカードに変えてくれます。 このブログでは、どのリンクも同じ青い下線でした。GitHubのIssue、MDNのページ、各サービスのドキュメントが混ざった参考リンクの一覧も、見た目の同じテキストが縦に並ぶだけです。GitHubのように表示できないものかと考えました。 **そこで、このブログがよく引用するサイトへのリンクの前に、リンク先のブランドマークを付けるビルド時のrehypeプラグインを追加しました**。対象はGitHub、MDN、Vercel、Claudeのドキュメント、pnpm、git-scm、Astroのドキュメントです。 マークはsimple-iconsから取り出してSVGとしてインライン化しているので、**ページがこれらのサイトにリクエストを送ることはありません**。記事のソースも、Markdownのふつうのリンクのままです。 *Image: 参考リンクの一覧。pnpmのドキュメントへのリンクにはオレンジのpnpmマーク、GitHubのIssueへのリンクにはGitHubのOctocat、Vercelへのリンクには三角形のVercelマークが付いている* *プラグインを有効にすると、参考リンクの各リンクの前にそのサイトのマークが付きます。* ## rehypeプラグイン1つ、ページごとにスプライト1つ SVGスプライトとは、各アイコンを `id` 付きの `` として1回ずつ収めた、非表示の `` のことです。ページ内のどこでも `` でそのシンボルを描けるので、アイコンが何回出てきてもパスは1回しか書きません。 > **ちなみに** > > **なぜスプライトと呼ぶのか** > > スプライトはもともと、キャラクターやアイテムといったゲームの小さな画像のことです。多くのスプライトを1枚の画像にまとめ、必要な部分だけを切り出して使う方法をスプライトシートと呼びます。CSSスプライトやSVGスプライトもこの考え方を借りたもので、SVGスプライトは多くの `` を1つの `` にまとめ、`` で必要なものを取り出します。 *Image: ピクセルアートのスプライトシート。草地、木、屋根、柵、扉、小物などの16×16のタイルが1枚の画像に隙間なく並んでいる* *[KenneyのTiny Town](https://kenney.nl/assets/tiny-town)（CC0）。16×16のタイル132枚が1枚の画像に収められ、ゲームは描きたいタイルを切り出して使います。* **プラグインは、AstroがMarkdownとMDXの両方に渡す `unified()` プロセッサーに1項目追加するだけです**。記事ごとの設定は不要で、どの記事も3言語ともこのプラグインを通ります。 ```js title="astro.config.mjs" ins={2,5} import { rehypeTableScroll } from "./src/lib/rehype-table-scroll.ts"; import { rehypeLinkIcons } from "./src/lib/rehype-link-icons.ts"; // … markdown: { processor: unified({ rehypePlugins: [rehypeTableScroll, rehypeLinkIcons] }), }, ``` *Figure — PluginFlow: プラグインが変えるのはビルド後のHTMLだけで、MDXのソースには手を加えません。* プラグインは装飾するリンクごとに、アイコンとラベルの先頭1文字をspanで包み、アイコンから `` でシンボルを参照します。 ```html title="ビルド時にプラグインが生成する、マーク付きのリンク" pnpm/pnpm#12744 ``` spanに入れるのは、マークと先頭の1文字を同じ行に保ち、マークだけが行末に取り残されないようにするためです。1単語ではなく1文字にした理由は、後述の落とし穴1で説明します。 走査が終わると、そのページで使ったマークだけを `` として持つ `` を1つ、ビルド後のHTMLの末尾に追加します。そのため、Claudeのドキュメントへのリンクが十数個ある記事でも、Claudeのマークのパスは1回分しか入りません。このスプライトはビルド後のHTMLにしかなく、MDXのソースには現れません。 *Figure — SpriteReference: 各リンクは `` でマークを描き、ページ末尾にある1つのスプライト内の `` を参照します。* アイコンは `aria-hidden` なので、**スクリーンリーダーが読み上げるのはリンクのテキストだけで**、マークを画像として読み上げることはありません。CSSではアイコンを `1em` の大きさにし、`margin-inline: 0.2em 0.25em` で左右に余白を取っています。日本語や中国語ではリンクの直前の文字との間に何も入らないので、この余白が効きます。 ## どのリンクにマークが付くか マークが付くのは、ホスト名が固定の対応表に完全一致したリンクだけです。 | マーク | ホスト名 | | --- | --- | | [GitHub](https://github.com/) | `github.com`, `docs.github.com`, `github.blog` | | [MDN](https://developer.mozilla.org/) | `developer.mozilla.org` | | [Vercel](https://vercel.com/) | `vercel.com` | | [Claude](https://code.claude.com/) | `code.claude.com`, `platform.claude.com`, `docs.claude.com`, `support.claude.com` | | [pnpm](https://pnpm.io/) | `pnpm.io` | | [Git](https://git-scm.com/) | `git-scm.com` | | [Astro](https://docs.astro.build/) | `docs.astro.build` | このブログがよく引用し、かつsimple-iconsにマークがあるサイトを私が選びました。外部リンクすべてにマークを付けると、マークが何も伝えなくなります。表にないサイトへのリンクは、ふつうのリンクとして表示されます。 見出しのテキストは目次にも使われるので、見出しの中のリンクは対象外です。`code` や `pre` の中のリンクも飛ばします。脚注の参照を含む内部リンクは、そもそも対応表に一致しません。 *Figure — LinkDecision: 判定はすべてビルド時に行われます。プラグインがテキストに手を加えるのはGitHubへのリンクだけで、URLそのままのものは短縮形にし、Issue・プルリクエスト・コミットへのリンクには参照を付けます。* ### 書かれたラベルは残し、GitHubの短縮形を後ろに付ける Claude Codeは最初、GitHubへのリンクをすべてGitHub流の `owner/repo#59` 形式に書き換えることを提案しました。しかしClaude Codeが実装の前にこのブログの記事を調べたところ、**Issueへのリンクにはすでに手書きのラベルが付いていました**。書き方も `pnpm#12744`、`Issue #36123: …`、`withastro/astro issue #13996: …` とまちまちです。 これを `owner/repo#59` に置き換えると、そのIssueが何についてのものかが失われます。**そこで私は、ラベルを残したまま、その後ろに短縮形を付けることにしました**。Issue、プルリクエスト、コミットへのリンクは `ラベル (owner/repo#59)` と表示されます。この文にある[IDE拡張機能で `/add-dir` を使えるようにする要望](https://github.com/anthropics/claude-code/issues/36123)へのリンクが、その例です。 番号やSHAをすでに含むラベルには、何も付け足しません。この文の [Issue #36123](https://github.com/anthropics/claude-code/issues/36123) がその例です。[simple-icons](https://github.com/simple-icons/simple-icons) のようなリポジトリへのリンクも同様です。短縮形はリポジトリ名を繰り返すだけになるからです。 テキストがURLそのものであるリンクは、代わりにテキストを短縮形に置き換えます。`remark-github` も同じルールを採っています。形式はGitHubの自動リンクのドキュメントに従い、Issueやプルリクエストは `owner/repo#N`、コミットはリポジトリ名と7文字のSHA、リポジトリのトップは `owner/repo` になります。この文中のURLそのままのリンク https://github.com/remarkjs/remark-github も、そのように表示されます。 ```ts title="src/lib/rehype-link-icons.ts" const ref = githubRef(url); const only = children.length === 1 ? children[0] : undefined; if (only?.type === "text" && only.value === href) { if (ref) only.value = ref.short; } else if (ref?.named && !ref.named.test(textOf(link))) { children.push( { type: "text", value: " " }, { type: "element", tagName: "span", properties: { className: ["link-ref"] }, children: [{ type: "text", value: `(${ref.short})` }] }, ); } ``` `GITHUB_RESERVED` には、`features`、`orgs`、`settings`、`marketplace` といったGitHub自身のトップレベルのページを入れています。これがないと、URLそのままの `github.com/features/actions` が `features/actions` と表示され、存在しないリポジトリのように読めてしまいます。それ以外のパス、たとえば `blob/…` のファイルへのリンクはURLのまま残します。GitHubがその短縮形を定めていないからです。 ## マークをインラインSVGにした理由 > **ちなみに** > > **CSPとは** > > CSP（Content Security Policy）は、ページが画像やスクリプト、スタイルをどこから読み込んでよいかを、サイトがレスポンスヘッダーでブラウザーに伝える仕組みです。ルールに合わないリクエストは、ブラウザーがブロックします。 このサイトのCSPは `img-src 'self' data:` で、このサイト自身と `data:` の画像しか読み込めないため、**Googleのファビコンサービスやリンク先のサイトから取得するファビコンはブロックされます**。閲覧時に読み込めば、読者のIPアドレスをそのサービスやサイトに渡すことにもなります。そのため、マークは閲覧時にブラウザーで取得するのではなく、ビルドの時点でページに入っている必要があります。 マークは、すでに依存関係にあるsimple-iconsから取り出します。取り出すときは、マークが存在しなければ例外を投げるヘルパーを通します。 ```ts title="src/lib/brand-mark.ts" function lookup(slug: string): SimpleIcon { const icon = (simpleIcons as Record)[slug]; if (!icon) { throw new Error( `simple-icons has no export "${slug}". It may have been renamed, or removed ` + `over a trademark complaint. Check the package and update whichever table ` + `asked for it.`, ); } return icon; } ``` simple-iconsは実際にマークを削除します。**バージョン15.0.0では、1つのプルリクエストでAmazon Web ServicesとAmazonのマークがすべて削除されました**。そのため、このブログでVercelと同じくらい引用しているAWSのドキュメントへのリンクには、アイコンが付きません。汎用のアイコンで穴埋めはせず、ふつうのリンクのままにしました。W3CとIETFも、simple-iconsにはありません。 インライン化をSVGスプライトで行う案は、Claude Codeが出したものです。各マークを `data:` URIの背景画像として埋め込むスタイルシートを生成する方法もありましたが、スプライトならプラグインが出力するのはマークアップだけです。各ページには使ったマークだけが入り、対応表と同期させる生成済みのCSSファイルもありません。 ## ブランドカラーと、ダークモードで消える3つのマーク Claude Codeは、ライトモードでもダークモードでも見やすいように、すべてのマークをリンクと同じ色にすることを提案しましたが、私はそれぞれのマーク本来の色を使いたいと考えました。各マークには、simple-iconsが記録しているブランドカラーをそのまま使っています。 そのうち3色は黒です。このサイトのダークモードの背景 `#0b1120` に対して、**GitHubの `#181717` は1.05:1、MDNとVercelの `#000000` は1.12:1** しかありません。WCAGがグラフィックに求める3:1を大きく下回り、ダークモードではこの3つのマークが見えなくなっていました。そこで、これらに明るい色のバリエーションを用意するよう依頼しました。 プラグインはビルド時に、各マークとダークモードの背景とのコントラストを計算します。3:1を下回るマークには、クラスと、ブランドカラーを入れた `color` 属性を付けます。 ```html title="スプライト内の GitHub のシンボル" ``` ```css title="src/styles/global.css" .link-mark-ink { fill: light-dark(currentColor, var(--text-1)); } ``` `currentColor` は `color` 属性の値を読むので、ライトテーマではブランドカラーそのもの、ダークテーマではサイトの文字色になります。`light-dark()` は `color-scheme` に従い、ライトなら1つ目、ダークなら2つ目の値を使います。テーマの切り替えボタンもすでに `color-scheme` を設定しているので、**OSの設定でも切り替えボタンでも、同じようにマークの色が切り替わります**。 *Image: ダークモードの同じ参考リンク一覧。GitHubのOctocatとVercelの三角形が、水色のリンクの横に明るいグレーで描かれている* *ダークモードでは、GitHubとVercelのマークが文字色になります。* ## 3つの落とし穴：CJKのラベル、`