Remark プラグイン「remark-card」を自作して Astro 製ウェブサイトで使ってみた

導入

幼い頃から、魔法使いになることを夢見ていた──

この度、ようやくその念願が叶った。
しかしその能力は限定的で、リンゴをアップルパイに変えたり、嫌いな人をマリモッコリに変えたりはできない。代わりに、マークダウンを望み通りの HTML に変えることならできる。

ところで、Remark や Rehype を擁する文書変換エコシステム「Unified」の下では、世界各地に点在する有志たちによって、数多のプラグインが日夜開発・メンテナンスされている。
しかし調べた限りでは、「フィールド上にカードコンポーネントをマークダウン記法で召喚できる」と謳うものは存在しなかった。¹

そういう訳で、無いなら自分で作ろうということに相成った。今なら、空だって飛べる気がする。

想定読者

Remark プラグインを自分で作ってみたい
remark-cardに興味がある
マークダウン/MDX のブログに彩りを添えようと躍起になっている

現時点での私の習熟度

記事執筆時点での私の習熟度は次の通り。

ソフトウェアエンジニアとして計 3 年の経験あり(勤続ではない)
JavaScript、TypeScript とはかれこれ 4 年程の付き合いになる
NPM パッケージは公開したことがない

本題

Github リポジトリはこちら。インストール方法については README に認めてあるので、ここでは触れない。

GitHub - brklntmhwk/remark-card: A remark plugin to parse card component(s) A remark plugin to parse card component(s). Contribute to brklntmhwk/remark-card development by creating an account on GitHub.

github.com

A remark plugin to parse card component(s). Contribute to brklntmhwk/remark-card development by creating an account on GitHub.

使い方

remark-cardはcard-grid、cardの 2 つのマークダウン方言を提供する。
前者はカードを複数表示する場合にラッパーの役割を果たし、後者はカード単体である。

Note

以降の具体例では、簡単のため、HTML に限って本記事の趣旨から外れる記述(class等)を削ぎ落としている。

card

まずカード単体の記法はこちら。

1
:::card
2
![younagi.dev](../../../assets/images/younagidev.jpg)
3
younagi.dev
4
:::

これがイイ感じの HTML に変換され・・。

1
<div>
2
  <div class="image-container">
3
    <figure>
4
      <picture>
5
        <source srcset="...">
6
        <source srcset="...">
7
        <img src="..." alt="younagi.dev">
8
      </picture>
9
      <figcaption>younagi.dev</figcaption>
10
    </figure>
11
  </div>
12
  <div class="content-container">
13
    younagi.dev
14
  </div>
15
</div>

最終的な出力はコレだ。

younagi.dev

card-grid

次にカードグリッドの中に複数のカードを並べてみよう。

1
::::card-grid
2
:::card
3
![younagi.dev](../../../assets/images/younagidev.jpg)
4
younagi.dev 其の一
5
:::
6
:::card
7
![younagi.dev](../../../assets/images/younagidev.jpg)
8
younagi.dev 其の二
9
:::
10
:::card
11
![younagi.dev](../../../assets/images/younagidev.jpg)
12
younagi.dev 其の三
13
:::
14
::::

これが HTML に変換されると次のようになる。

1
<div>
2
  <div>
3
    <div class="image-container">
4
      <figure>
5
        <picture>
6
          <source srcset="...">
7
          <source srcset="...">
8
          <img src="..." alt="younagi.dev 其の一">
9
        </picture>
10
        <figcaption>younagi.dev 其の一</figcaption>
11
      </figure>
12
    </div>
13
    <div class="content-container">
14
      younagi.dev 其の一
15
    </div>
16
  </div>
17
  <div>
18
    <div class="image-container">
19
      <figure>
20
        <picture>
21
          <source srcset="...">
22
          <source srcset="...">
23
          <img src="..." alt="younagi.dev 其の二">
24
        </picture>
25
        <figcaption>younagi.dev 其の二</figcaption>
26
      </figure>
27
    </div>
28
    <div class="content-container">
29
      younagi.dev 其の二
30
    </div>
31
  </div>
32
  <div>
33
    <div class="image-container">
34
      <figure>
35
        <picture>
36
          <source srcset="...">
37
          <source srcset="...">
38
          <img src="..." alt="younagi.dev 其の三">
39
        </picture>
40
        <figcaption>younagi.dev 其の三</figcaption>
41
      </figure>
42
    </div>
43
    <div class="content-container">
44
      younagi.dev 其の三
45
    </div>
46
  </div>
47
</div>

そして最終的な出力はこちら。

younagi.dev 其の一

younagi.dev 其の二

younagi.dev 其の三

Astro で使う

実は、当サイトでも既にカードコンポーネントが随所に鏤められている。

作品

younagi.dev

Astro で Remark や Rehype のプラグインを利用するには、ルート直下にある専用のコンフィグファイルで下記の手続きが必要となる。

1
import { defineConfig /* ... */ } from "astro/config";
2
import remarkCard, { type Config as RemarkCardConfig } from 'remark-card';
3
// ...
4

5
export default defineConfig({
6
  // ...
7
  markdown: {
8
    remarkPlugins: [
9
      // ...
10
      [
11
        remarkCard,
12
        {
13
          customHTMLTags: {
14
            enabled: true,
15
          },
16
          cardGridClass: 'card-grid',
17
          cardClass: 'card',
18
        } satisfies RemarkCardConfig,
19
      ],
20
      // ...
21
    ],
22
    // ...
23
  }
24
  // ...
25
});

一応これだけでプラグインは動くようになるのだが、Astro コンポーネントを使って HTML タグやスタイルを細かく調整したい場合は、もうひと手間必要となる。

私の場合、remark-cardによってcard、card-gridタグに変換された箇所を、更にそれぞれCard.astro、CardGrid.astroへと変換している。詳細は下記ソースコードを確認してほしい。

younagi.dev/src/components/elements/Card at main · brklntmhwk/younagi.dev Website of Nagi, by Nagi, and for nobody. Contribute to brklntmhwk/younagi.dev development by creating an account on GitHub.

github.com

Website of Nagi, by Nagi, and for nobody. Contribute to brklntmhwk/younagi.dev development by creating an account on GitHub.

そして MDX の作法に倣い、カスタムコンポーネントとして<Content />タグにこれらを引き渡せば取引完了だ。下記がその一例である。

1
import { Card, CardGrid } from '@/components/elements/Card';
2
// ...
3

4
export const mdxComponents = {
5
  // ...
6
  card: Card,
7
  'card-grid': CardGrid,
8
  // ...
9
};

1
---
2
import BlogLayout from '@/layouts/BlogLayout.astro';
3
import { mdxComponents } from '@/lib/mdx-components';
4
import type { GetStaticPaths } from 'astro';
5
// ...
6

7
export const getStaticPaths = (async () => {
8
  // ...
9
}) satisfies GetStaticPaths;
10

11
const { entry } = Astro.props;
12
const { Content, headings } = await entry.render();
13
---
14

15
<BlogLayout entry={{ ...entry }} {headings}>
16
  <Content components={mdxComponents} />
17
</BlogLayout>

開発後記

このままでは README と書いてあることがほとんど変わらないので、技術選定について少し真面目に振り返ろうと思う。

言語: ~~JavaScript~~ TypeScript
- 型がないと生まれたての小鹿のように足元が覚束なくなるため TypeScript で書くことにした
- ~~CommonJS~~ ESM の作法に倣って書いている
マークダウン記法: Generic directives/plugins syntax
- はじめは知る人が見たらひっくり返るようなド方言を編み出し、開発を進めていたが、より一般に浸透していそうなこちらの記法に方向転換
- :::や::::など
テストランナー & パッケージマネージャ: Bun
- JavaScript ランタイム、テストランナー、パッケージマネージャ、と複数の顔を併せ持つ肉まん君
- テストコードが Jest 互換で馴染みがあり、移行しやすい
- 目新しさとパフォーマンスの高さに惹かれ、採用

開発にあたり、先人たちの記したソースコードを浴びるように摂取したのだが、大半が JavaScript に JSDoc の組み合わせで書かれていた。
製品コードを書く場合は総じてこの組み合わせの方が良いと思う ² が、今回は零細なプロジェクトなので慣れ親しんだ TypeScript で書くことにした。

結び

実はremark-cardの後、立て続けにremark-videoという Remark プラグインも開発・リリースした。

GitHub - brklntmhwk/remark-video: A remark plugin to parse HTML5 video components A remark plugin to parse HTML5 video components. Contribute to brklntmhwk/remark-video development by creating an account on GitHub.

github.com

A remark plugin to parse HTML5 video components. Contribute to brklntmhwk/remark-video development by creating an account on GitHub.

当初はそちらも記事にしようと画策していたが、remark-card程の手間がかかっておらず、あまり書くこともないため断念した。³

カードはカードでも、リンクカードなら沢山ヒットしたのだが・・。 ↩
TypeScript で書かない為、トランスパイルの手間が省ける。しかし同時に、JSDoc の補助機能により型定義の恩恵に与ることもできる。
更に JSDoc には元々ドキュメントの側面もあり、その作法に則って書くだけで読み手とコードの意図についてコミュニケーションが取りやすい。 ↩
有り体に言えば、面倒くさくなっただけである。 ↩

Remark プラグイン「remark-card」を自作して Astro 製ウェブサイトで使ってみた

#導入

#想定読者

#現時点での私の習熟度

#本題

#使い方

#card

#card-grid

#Astro で使う

#開発後記

#結び

導入

想定読者

現時点での私の習熟度

本題

使い方

card

card-grid

Astro で使う

開発後記

結び