ブログにリンクカードを実装した

link-card

経緯

Zenn や note などのメジャーなブログサイトだと、記事内にリンクを配置したら、そのサイトの OG 情報を綺麗に表示してくれてかなりオシャレ。なので、自分のブログにも実装したいと思った。

リンクカードで表示する時と、単に URL を表示するのとでは印象がだいぶ変わるので、リンクカード実装するだけで見栄えが上がる。

実装方針

前回のブログは Next.js だったので、SSR とか API とか自前で完結したが、今回は Astro なのでそうはいかない。

そもそもリンクカードの実装に必要な要件は、

URL をフェッチ
HTML をパースして OG 情報を取得
適切なスタイルと挙動のカードを表示

これをやらねばならない。また、リンク先の情報は更新される可能性がある ので、静的ビルド時にやるのは少し微妙。また、クライアント側で取得するのは CORS に阻まれてできない。なので、なるべく最新の情報を反映した状態で表示するには、<iframe> を使って埋め込むのが一番楽になると思う。

実際、Zenn はそのように実装されている。

なので以下の流れとなる。

マークダウンからリンクを抽出
<iframe> に置き換え
サーバー側で情報を取得してレンダリング
表示

サーバー側の実装について見ていく。

サーバー

「サーバーを用意してリクエストに応じて HTML を返す」を実行する選択肢はいくつかあるが、Cloudflare 大好きなので Hono と Cloudflare Workers を使うことにした。

Hono には JSX の機能があって、サーバーサイドでレンダリングして HTML を返すことができる。すごい。

(今気づいたけど、なぜか hono の OGP をちゃんと取得できてないっぽいので後で修正…)

React みたいなフックもあるが、今回は使わなかった。

ここで、指定されたリンク先にアクセスして HTML をパースすることなんだが、HTML のパースは一筋縄ではいかない。なぜなら、Workers ではメジャーな DOM 操作のライブラリは使えない からだ。

そこでどうするかというと、Workers 上で使用できる HTMLRewriter を応用して情報を抽出する。これは、「workers リンクカード」などで調べるとヒットする先人の方法に倣った。マジでめちゃくちゃ役に立った。

みんなやることは同じなんだね〜。

自分はこれらの記事を参考に、以下のように実装した。

1
export interface OGPData {
2
  title?: string | null;
3
  description?: string | null;
4
  image?: string | null;
5
  url?: string | null;
6
  siteName?: string | null;
7
  type?: string | null;
8
  favicon?: string | null;
9
}
10

11
class OGPParser {
12
  origin: string = "";
13
  ogp: OGPData = {};
14

15
  constructor(url: string) {
16
    this.origin = new URL(url).origin;
17
  }
18

19
  meta(element: Element) {
20
    const property = element.getAttribute("property");
21
    const content = element.getAttribute("content");
22

23
    switch (property) {
24
      case "og:title": {
25
        this.ogp.title = content;
26
        break;
27
      }
28
      case "og:description": {
29
        this.ogp.description = content;
30
        break;
31
      }
32
      case "og:image": {
33
        this.ogp.image = new URL(content || "", this.origin).href;
34
        break;
35
      }
36
      case "og:url": {
37
        this.ogp.url = new URL(content || "", this.origin).href;
38
        break;
39
      }
40
      case "og:site_name": {
41
        this.ogp.siteName = content;
42
        break;
43
      }
44
      case "og:type": {
45
        this.ogp.type = content;
46
        break;
47
      }
48
    }
49
  }
50

51
  link(element: Element) {
52
    const rel = element.getAttribute("rel") ?? "";
53
    const href = element.getAttribute("href");
54

55
    const rels = rel.split(" ").map((r) => r.toLowerCase());
56

57
    if (rels.includes("icon")) {
58
      this.ogp.favicon = new URL(href || "", this.origin).href;
59
    }
60
  }
61

62
  element(element: Element) {
63
    const tagName = element.tagName.toLowerCase();
64

65
    switch (tagName) {
66
      case "meta": {
67
        this.meta(element);
68
        break;
69
      }
70
      case "link": {
71
        this.link(element);
72
        break;
73
      }
74
    }
75
  }
76
}
77

78
export async function getOGP(url: string): Promise<OGPData> {
79
  const host = new URL(url).host;
80
  const userAgent = getDynamicUserAgent(host);
81

82
  const res = await fetch(url, {
83
    headers: {
84
      "User-Agent": userAgent,
85
    },
86
    redirect: "follow",
87
  });
88
  if (!res.ok) {
89
    throw new Error(`Failed to fetch OGP data from ${url}`);
90
  }
91

92
  const contentType = res.headers.get("content-type");
93
  if (contentType?.startsWith("image/")) {
94
    throw new Error(`The URL ${url} points to an image, not a webpage.`);
95
  }
96

97
  const ogpParser = new OGPParser(url);
98

99
  // https://github.com/oven-sh/bun/issues/4408#issuecomment-1736976282
100
  const _res = new HTMLRewriter().on("meta, link", ogpParser).transform(res);
101
  await _res.text();
102

103
  // パースしたものを取得
104
  const ogp = ogpParser.ogp;
105

106
  // OGP 画像がちゃんと存在するかチェック
107
  if (ogp.image) {
108
    const res = await fetch(ogp.image, {
109
      method: "HEAD",
110
      headers: {
111
        "User-Agent": userAgent,
112
      },
113
      redirect: "follow",
114
    });
115

116
    // 適切に取得できなかったら削除
117
    if (!res.ok) {
118
      delete ogp.image;
119
    }
120
  }
121

122
  // favicon がちゃんと存在するかチェック
123
  if (ogp.favicon) {
124
    const res = await fetch(ogp.favicon, {
125
      method: "HEAD",
126
      headers: {
127
        "User-Agent": userAgent,
128
      },
129
      redirect: "follow",
130
    });
131

132
    // 適切に取得できなかったら削除
133
    if (!res.ok) {
134
      delete ogp.favicon;
135
    }
136
  }
137

138
  return ogp;
139
}

HTMLRewriter については以下の記事が詳しかった。

また、Workers じゃなくても Bun に同じものが実装されているので、そっちを使うこともできる。

ただし、Bun の HTMLRewriter の挙動にバグ?があるので共有しておく。上記のコードで変に await しながら、返り値を使っていないものがある。

1
  // https://github.com/oven-sh/bun/issues/4408#issuecomment-1736976282
2
  const _res = new HTMLRewriter().on("meta, link", ogpParser).transform(res);
3
  await _res.text();

これはこの issue にある通り、Response の body を消費しないと、HTMLRewriter が最後まで通らず、途中で抽出が終わって正しくパースされない。

ここら辺の情報が少なくて、Cloudflare Workers のサンプルコードを使っているとずっと解決しなくてしばらく困っていた。

(ちょくちょく正常に OGP 取得できないのは謎…後で原因究明…)

このようにして OGP 情報を抽出したら、あとは Hono の JSX 機能を使って HTML を返す。

1
import { jsxRenderer } from "hono/jsx-renderer";
2
import { Link, ViteClient } from "vite-ssr-components/hono";
3

4
export const renderer = jsxRenderer(({ children }) => {
5
  return (
6
    <html>
7
      <head>
8
        <ViteClient />
9
        <Link href="/src/style.css" rel="stylesheet" />
10
        <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
11
      </head>
12
      <body>
13
        {children}
14
        <script src="/load-theme.js"></script>
15
      </body>
16
    </html>
17
  );
18
});

JS を読み込んでるのは後述。

こういう TailwindCSS を挟んだレンダラーを用意して OGP 情報を描画するようにした。一応 KV も使ってキャッシュを行なっている。


37 collapsed lines
1
import { Hono } from "hono";
2
import { renderer } from "./renderer";
3
import { getOGP, OGPData } from "./lib/ogp";
4
import { raw } from "hono/html";
5

6
type Bindings = {
7
  OGP_CACHE: KVNamespace;
8
};
9

10
const app = new Hono<{
11
  Bindings: Bindings;
12
}>();
13

14
const getCachedOGP = async (
15
  url: string,
16
  cache: KVNamespace
17
): Promise<OGPData> => {
18
  const cached = await cache.get(url, "json");
19
  if (cached) {
20
    return cached as OGPData;
21
  }
22

23
  const ogp = await getOGP(url);
24
  await cache.put(url, JSON.stringify(ogp), { expirationTtl: 60 * 60 }); // Cache for 1 hour
25
  return ogp;
26
};
27

28
app.use(renderer);
29

30
app.get("/", (c) => {
31
  return c.text("Hello!");
32
});
33

34
app.get("/message", (c) => {
35
  return c.render(<></>);
36
});
37

38
app.get("/embed", async (c) => {
39
  const { url } = c.req.query();
40
  if (!url) {
41
    return c.text("Please provide a URL query parameter.", 400);
42
  }
43

44
  try {
45
    const ogp = await getCachedOGP(decodeURIComponent(url), c.env.OGP_CACHE);
46

47
    return c.render(
48
      <div
49
        class={
50
          "flex h-screen w-full max-h-40 rounded-xl tracking-tight group bg-linkcard"
51
        }
52
      >
53
        <div
54
          class={
55
            "min-w-0 w-full h-full py-5 flex flex-col justify-between px-6"
56
          }
57
        >
58
          <h1 class={"text-lg leading-[1.1] line-clamp-2 font-semibold"}>
59
            {raw(ogp.title ?? "")}
60
          </h1>
61
          <p class={"text-sm truncate text-secondary w-full"}>
62
            {raw(ogp.description ?? "")}
63
          </p>
64

65
          <p class={"text-sm group-hover:underline"}>{ogp.url ?? ""}</p>
66
        </div>
67

68
        {ogp.image && (
69
          <div class={"max-w-1/3 w-80 flex flex-col items-center"}>
70
            <img
71
              class={"w-full h-full object-cover"}
72
              src={raw(ogp.image)}
73
              alt={ogp.title || "OGP Image"}
74
            />
75
          </div>
76
        )}
77
      </div>
78
    );
79
  } catch (error) {
80
    const message =
81
      error instanceof Error ? error.message : "An error occurred";
82

83
    return c.render(
84
      <div
85
        class={
86
          "flex w-full justify-between gap-6 rounded-xl shadow-sm tracking-tight "
87
        }
88
      >
89
        <div class={"grow min-w-80 py-6 flex flex-col gap-2 px-4"}>
90
          <h1 class={"text-xl font-semibold"}>{message}</h1>
91
          <p class={"text-sm"}>Please check the URL and try again.</p>
92
          <p class={"text-sm"}>url={url}</p>
93
        </div>
94
      </div>
95
    );
96
  }
97
});
98

99
export default app;

これをすると、/embed?url=... にアクセスすると、指定された URL の OGP 情報を取得してカードを表示してくれる。KV にキャッシュもするので、短時間内のアクセスならリンク先に大量のリクエストを送ることも回避して高速にレスポンスを返せる。欠点としては、OGP 情報が更新されてもすぐに反映できない点。ただ、そうそう頻繁には変わらないだろうし、そこまでリアルタイム性が要求されるような要件ではないので、あんま問題はないと思う。若干開発時にキャッシュ消したりが面倒になるくらい。

これでサーバー側でリンクカードをレンダリングする処理はできたので、クライアント側で表示する処理。

クライアント

クライアント側では、パースしたマークダウンのリンクを <iframe> を持ちいたリンクカードに置き換える処理を行う。

これを実現するには、rehype のカスタムプラグインを用いる。参考記事に上げてる記事が詳しいので、そちらを参照。

うちのサイトでは以下のような実装になった。

1
import type { ElementContent, Root } from "hast";
2
import { visit } from "unist-util-visit";
3

4
interface Options {
5
  linkcardUrl: string;
6
  target?: "_blank" | "_self" | "_parent" | "_top";
7
  rel?: string[];
8
}
9

10
const rehypeLinkCard = ({ linkcardUrl, target, rel }: Options) => {
11
  return (tree: Root) => {
12
    visit(tree, "element", (node, index, parent) => {
13
      // paragraph じゃなかったら return
14
      if (!parent || typeof index !== "number" || node.tagName !== "p") {
15
        return;
16
      }
17

18
      // 空のテキストノードを除外
19
      const children = node.children.filter(
20
        (child) => child.type !== "text" || child.value.trim() !== "",
21
      );
22

23
      // 子要素が<a>タグ一つだけかチェック
24
      if (children.length !== 1) {
25
        return;
26
      }
27

28
      const linkNode = children[0];
29
      if (linkNode.type !== "element" || linkNode.tagName !== "a") {
30
        return;
31
      }
32

33
      const href = linkNode.properties?.href;
34
      if (typeof href !== "string") {
35
        return;
36
      }
37

38
      // TODO: 内部リンクを特殊として扱う？
39

40
      const src = new URL(`/embed?url=${encodeURIComponent(href)}`, linkcardUrl)
41
        .href;
42

43
      // 置き換える要素を object として定義 (jsx の代わり)
44
      const elem = {
45
        type: "element",
46
        tagName: "span",
47
        properties: {
48
          class: "linkcard",
49
        },
50
        children: [
51
          {
52
            type: "element",
53
            tagName: "a",
54
            properties: {
55
              target: target ?? "_blank",
56
              rel: rel ?? ["nofollow", "noreferrer", "noopener"],
57
              href: href,
58
            },
59
            children: [
60
              {
61
                type: "element",
62
                tagName: "iframe",
63
                properties: {
64
                  src: src,
65
                },
66
                children: [],
67
              },
68
            ],
69
          },
70
        ],
71
      } satisfies ElementContent;
72

73
      parent.children.splice(index, 1, elem);
74
    });
75
  };
76
};
77

78
export default rehypeLinkCard;

1
export default defineConfig({
2
    ...
3
    markdown: {
4
      syntaxHighlight: false,
5
      rehypePlugins: [
6
        [
7
          rehypeLinkCard,
8
          {
9
            linkcardUrl: SITE.linkcard,
10
            target: "_blank",
11
            rel: ["nofollow", "noreferrer", "noopener"],
12
          },
13
        ],
14
        ...
15
      ]
16
    },
17
    ...
18
})

置き換え条件として、

親ノードが <p> タグであること
その子要素が空のテキストノードを除いて <a> タグ一つだけであること
href 属性が存在すること

を判定して、満たす要素を <iframe> のリンクカードに置き換えるようにした。これは Gemini か ChatGPT が書いたので、もしかしたら変な処理になっているかもしれない。まだちゃんと理解できていない…

リンクカードの URL はサイトの config で指定したベース URL に /embed?url=... を付与したものにしている。この時、encodeURIComponent で / などを含めて URL エンコードしている (そうしないとサーバーの Hono でちゃんとパースできなかった…)

サーバー側でカードの UI を設定したので、クライアントでは <iframe> を持った <a> タグを生成するだけで OK となる。最近知ったんだけど、<a> タグって結構いろんなもの入れてもいいらしい。Zenn は <a> と <iframe> が分離されていたので、てっきりダメなのかと思っていた。シンプルにネストした方が処理が楽なので嬉しい。

テーマの反映

クライアント側でリンクカードを表示するのはこれだけで完了となる。このブログサイトには、カスタムのテーマカラーを設定する機能があるのだが、<iframe> リンクカードの内側と外側でカラーテーマがそのままでは同期されない。しかも、クロスオリジンなのでダイレクトな操作ができないと思う。

なので、クライアントから <iframe> に対してメッセージを送信して、サーバー側のフロント JS でハンドルする処理が必要となる。これが先ほどレンダラーに入っていた load-theme.js である。中身はブログサイトの方で使っているものとほぼ同じだが、メッセージの受信をトリガーに追加している。


92 collapsed lines
1
// To avoid redeclaration errors
2
const theme = (() => {
3
    const localStorageTheme = localStorage?.getItem("theme") ?? "";
4
    if (["dark", "light"].includes(localStorageTheme)) {
5
    return localStorageTheme;
6
    }
7
    if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
8
    return "dark";
9
    }
10
    return "light";
11
})();
12

13
const setTheme = (theme) => {
14
    document.documentElement.setAttribute("data-theme", theme);
15
    document.documentElement.classList.remove("scheme-dark", "scheme-light");
16
    document.documentElement.classList.add(
17
        theme === "dark" ? "scheme-dark" : "scheme-light",
18
    );
19
    window.localStorage.setItem("theme", theme);
20
};
21

22
// <!-- hue angle -->
23

24
// To avoid redeclaration errors
25
const DEFAULT_HUE = 256;
26

27
const applyThemeHue = (angle) => {
28
    const dataTheme =
29
    document.documentElement.getAttribute("data-theme") ?? "light";
30

31
    const properties = {
32
    light: {
33
        background: `oklch(100% 0.01 ${angle}deg)`,
34
        foreground: `oklch(14.5% 0.05 ${angle}deg)`,
35
        secondary: `oklch(97% 0.01 ${angle}deg)`,
36
        border: `oklch(92.2% 0.015 ${angle}deg)`,
37
        input: `oklch(92.2% 0.015 ${angle}deg)`,
38
        popover: `oklch(100% 0.01 ${angle}deg)`,
39
    },
40
    dark: {
41
        background: `oklch(20% 0.01 ${angle}deg)`,
42
        foreground: `oklch(98.5% 0.03 ${angle}deg)`,
43
        secondary: `oklch(25% 0.01 ${angle}deg)`,
44
        border: `oklch(25% 0.015 ${angle}deg)`,
45
        input: `oklch(25% 0.015 ${angle}deg)`,
46
        popover: `oklch(24% 0.01 ${angle}deg)`,
47
    },
48
    };
49
    if (!Object.keys(properties).includes(dataTheme)) {
50
    console.warn(
51
        `Theme "${dataTheme}" not found. Using default properties.`,
52
    );
53
    return;
54
    }
55

56
    Object.entries(properties[dataTheme]).forEach(([key, value]) => {
57
    document.documentElement.style.setProperty(`--${key}`, value);
58
    });
59
};
60

61
const storeHue = (angle) => {
62
    localStorage.setItem("theme-hue", angle.toString());
63
};
64

65
const getHue = () => {
66
    const storedHue = localStorage?.getItem("theme-hue");
67
    return storedHue ? parseFloat(storedHue) : DEFAULT_HUE; // Default to 256 if not set
68
};
69

70
// Initialize the theme hue
71
const hue = getHue();
72

73
// apply theme without flashing
74
const element = document.documentElement;
75
element.classList.add("[&_*]:transition-none"); // disable animation
76

77
// color theme
78
document.documentElement.setAttribute("data-theme", theme);
79
document.documentElement.classList.add(
80
    theme === "dark" ? "scheme-dark" : "scheme-light",
81
);
82
window.localStorage.setItem("theme", theme);
83

84
// hue
85
applyThemeHue(hue);
86
storeHue(hue); // Store the initial hue if not already set
87

88
requestAnimationFrame(() => {
89
    element.classList.remove("[&_*]:transition-none");
90
}); // enable animation
91

92

93
// handle messages
94
window.addEventListener("message", (event) => {
95
    // TODO: origin check?
96

97
    const { type, theme, hue } = event.data;
98
    if (type === "set-theme" && typeof theme === "string" && typeof hue === "number") {
99
        // color theme
100
        setTheme(theme);
101

102
        // hue
103
        applyThemeHue(hue);
104
        storeHue(hue); // Store the new hue
105
    }
106
});

Hono の静的アセット配信機能を用いて、/load-theme.js にアクセスしたときにこれが返ってくるようにしている。Hono JSX だとクライアントサイドの JS を記述する方法がいまいちわからなかったのでこうしている… 機能しているのでまあヨシ。

このように、クライアント側と同じテーマの処理をすることで、最初の表示時やテーマの更新時に一緒に同じテーマカラーで表示されるようになる。

実際にこのサイトのテーマを変更してみるとわかりやすいと思う。

まとめ

HTMLRewriter を用いてパースした OGP 情報を元に、Workers でリンクカードをサーバーサイドレンダリングし、Astro で rehype プラグインを用いて <iframe> からそれを表示することで、ブログにリンクカードを表示することができた。また、リンクカードとブログサイトのテーマカラーを同期することもできた。

記事書き始めたのは 8/27 くらいのはずだったんだけど、忙しかったりで全然書き終わらなかった…

License under CC BY 4.0 https://creativecommons.org/licenses/by/4.0/deed.ja

ブログに​リンクカードを​実装した

成果物

経緯

実装方針

サーバー

クライアント

テーマの反映

まとめ

ブログにリンクカードを実装した