Go back

remark-callout を試してみた - Obsidian風のコールアウト記法をマークダウンで

はと🐤テック

Disclaimer: This article was written by AI and may contain inaccuracies or errors.

Table of contents

Open Table of contents

はじめに

マークダウンで技術文書やブログを書いていると、「ここは特に注意してほしい」「これは重要なヒント」といった情報を視覚的に目立たせたくなることがあります。

Obsidianというノートアプリでは、以下のような記法でコールアウト（callout）と呼ばれる装飾ブロックを作成できます：

> [!note] 覚えておきたいこと
> ここに本文を書きます

このようなコールアウト記法を、通常のマークダウン処理でも使えるようにしてくれるのが remark-callout です。

今回、実際にこのプラグインを試してみたので、セットアップから動作確認までの過程をレポートします。

remark-callout とは

remark-calloutは、remark（マークダウンパーサー）のプラグインで、Obsidian風のコールアウト記法を解析してHTMLに変換してくれます。

主な特徴

セットアップ

インストール

まず、パッケージをインストールします：

npm install @r4ai/remark-callout

または

pnpm add @r4ai/remark-callout

Astroでの設定

Astroプロジェクトで使う場合、astro.config.ts にプラグインを追加します：

import { defineConfig } from "astro/config";
import remarkCallout from "@r4ai/remark-callout";

export default defineConfig({
  markdown: {
    remarkPlugins: [
      // 他のプラグイン...
      remarkCallout,
    ],
  },
});

これで、マークダウンファイル内でコールアウト記法が使えるようになります。

実際に試してみる

1. 基本的なコールアウト

まず、シンプルなコールアウトを試してみました：

> [!note]
> これは note タイプのコールアウトです

このマークダウンは以下のHTMLに変換されました：

<div data-callout data-callout-type="note">
  <div data-callout-title>Note</div>
  <div data-callout-body>
    <p>これは note タイプのコールアウトです</p>
  </div>
</div>

data-callout-type 属性にタイプ名が設定されるので、CSSでスタイリングしやすい構造になっています。

実際にレンダリングされた例：

Note

これは note タイプのコールアウトです。この記事で remark-callout プラグインが正しく動作していることを確認できます。

2. 様々なタイプ

いくつかのタイプを試してみたところ、以下のタイプが動作することを確認できました：

> [!tip]
> ここに便利なヒントを書きます

> [!warning]
> ここに警告メッセージを書きます

以下、実際の表示例です：

Note

これは note タイプのコールアウトです。一般的なメモを提供する際に使用します。

Info

これは info タイプのコールアウトです。補足情報や追加の説明を提供する際に使用します。

Tip

これは tip タイプのコールアウトです。便利なヒントやコツを共有する際に効果的です。

Important

これは important タイプのコールアウトです。特に重要なポイントを際立たせることができます。

Warning

これは warning タイプのコールアウトです。警告が必要な情報を強調する際に使用します。

Caution

これは caution タイプのコールアウトです。注意が必要な情報を強調する際に使用します。

3. カスタムタイトル

タイプの後にテキストを追加すると、タイトルをカスタマイズできます：

> [!note] 覚えておきたいこと
> カスタムタイトルが設定されました

生成されるHTML：

<div data-callout data-callout-type="note">
  <div data-callout-title>覚えておきたいこと</div>
  <div data-callout-body>
    <p>カスタムタイトルが設定されました</p>
  </div>
</div>

実際の表示例：

覚えておきたいこと

カスタムタイトルを設定することで、より具体的な見出しを付けることができます。

プロからのアドバイス

タイトルを工夫することで、読者の理解を深めることができます。

4. 複数行と複雑なコンテンツ

コールアウトの中には、複数段落やリスト、コードブロックも含められます：

> [!info] セットアップ手順
> 以下の手順で設定してください：
>
> 1. パッケージをインストール
> 2. 設定ファイルを編集
> 3. 開発サーバーを起動
>
> \```bash
> npm install
> \```

実際に試したところ、コードブロックもリストも正しく表示されることを確認できました。

実際の表示例：

セットアップ手順

remark-callout を使い始めるには、以下の手順に従ってください：

  1. パッケージマネージャーを使ってインストール
  2. Astro の設定ファイルにプラグインを追加
  3. スタイルを定義（必要に応じて）
  4. マークダウンファイルで使用開始

複数の段落や、太字、斜体などのマークダウン記法も使用できます。

5. 折りたたみ可能なコールアウト

タイプの後に - または + を付けると、折りたたみ可能なコールアウトになります：

> [!note]- デフォルトで折りたたまれている
> この内容は最初は隠れています

> [!note]+ デフォルトで展開されている
> この内容は最初から表示されています

これらは <details> と <summary> 要素として出力されます：

<details data-callout data-callout-type="note">
  <summary data-callout-title>デフォルトで折りたたまれている</summary>
  <div data-callout-body>
    <p>この内容は最初は隠れています</p>
  </div>
</details>

<details data-callout data-callout-type="note" open>
  <summary data-callout-title>デフォルトで展開されている</summary>
  <div data-callout-body>
    <p>この内容は最初から表示されています</p>
  </div>
</details>

実際の表示例（クリックして展開・折りたたみできます）：

追加の詳細情報（クリックで展開）

この内容は最初は折りたたまれています。長い補足説明や詳細な情報を含める際に便利です。

  • ページをすっきり保てる
  • 必要な人だけが詳細を確認できる
  • JavaScriptなしでネイティブに動作
重要なヒント（デフォルトで表示）

この内容は最初から展開されています。重要だけど長い情報を提供する際に使えます。

6. スタイリング

プラグインはHTMLの構造を提供してくれますが、見た目のスタイルは自分で定義する必要があります。

Tailwind CSSを使った例：

/* 基本スタイル */
[data-callout] {
  @apply my-4 rounded-lg border-l-4 p-4;
}

[data-callout-title] {
  @apply mb-2 font-bold;
}

/* タイプ別の色分け */
[data-callout][data-callout-type="note"] {
  @apply border-blue-500 bg-blue-50 dark:bg-blue-950/30;
}
[data-callout][data-callout-type="note"] [data-callout-title] {
  @apply text-blue-700 dark:text-blue-400;
}

[data-callout][data-callout-type="warning"] {
  @apply border-yellow-500 bg-yellow-50 dark:bg-yellow-950/30;
}
[data-callout][data-callout-type="warning"] [data-callout-title] {
  @apply text-yellow-700 dark:text-yellow-400;
}

/* 折りたたみ用のアイコン */
details[data-callout] summary[data-callout-title]::before {
  content: "▶ ";
  @apply inline-block transition-transform;
}
details[data-callout][open] summary[data-callout-title]::before {
  @apply rotate-90;
}

このようなスタイルを設定することで、タイプごとに異なる色で表示され、折りたたみ時にはアイコンがアニメーションする、視覚的に分かりやすいコールアウトになります。

動作確認

実際にテストスクリプトを作成して、プラグインの動作を確認しました：

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkCallout from "@r4ai/remark-callout";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import { readFileSync } from "fs";

const markdown = readFileSync("test-callout.md", "utf-8");

const result = await unified()
  .use(remarkParse)
  .use(remarkCallout)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(markdown);

console.log(String(result));

このスクリプトで様々なパターンのコールアウトをテストし、期待通りのHTMLが生成されることを確認できました。

使ってみた感想

1. シンプルで直感的な記法

Obsidianを使ったことがある方なら、すぐに使い始められる記法です。初めての方でも > [!type] title という形式は覚えやすいと感じました。

2. HTML構造の設計が良い

data-* 属性を使った構造は、CSSでのスタイリングがしやすく、また他のJavaScriptとの連携もしやすいと思いました。特定のクラス名に依存しない設計は、プロジェクトごとの命名規則との衝突を避けられる点が良いです。

3. 折りたたみ機能の活用

<details> 要素を使った折りたたみ機能は、JavaScriptなしでネイティブに動作します。長い補足説明や詳細情報を含める際に、ページを読みやすく保てるのは便利だと感じました。

4. カスタマイズの余地

デフォルトでは最小限の機能のみを提供し、スタイリングやアイコンは利用者に任せる設計は、柔軟性があって良いと思いました。プロジェクトのデザインに合わせて自由に調整できます。

5. 複雑なコンテンツへの対応

コードブロック、リスト、複数段落など、様々なマークダウン要素をコールアウト内に含められるのは、実用的な場面で役立つと感じました。

気づいた点

1. スタイルは自分で用意する必要がある

プラグイン自体はスタイルを提供しないため、最初にCSSを書く必要があります。これは柔軟性のためのトレードオフですが、すぐに使い始めたい場合は少し手間がかかるかもしれません。

2. タイプの制限について

ドキュメントには明示的に「これらのタイプがサポートされている」というリストはありませんでした。設定によってはすべてのタイプ名を受け入れるようですが、どのタイプが利用可能かは、実際に試してみるか、設定で明示的に指定する必要があるようです。

3. Obsidianとの完全互換ではない

Obsidianには他にも様々なコールアウト機能がありますが、このプラグインは基本的な記法をサポートしています。高度な機能を使いたい場合は、カスタマイズが必要かもしれません。

このブログでの実装

このブログ記事自体が、remark-callout を使用した実例となっています。

実装内容

  1. パッケージのインストール

    pnpm add @r4ai/remark-callout

  2. Astro 設定の更新 (astro.config.ts)

    import remarkCallout from "@r4ai/remark-callout";

export default defineConfig({
  markdown: {
    remarkPlugins: [
      remarkToc,
      [remarkCollapse, { test: "Table of contents" }],
      remarkCallout, // 追加
    ],
  },
});

  3. スタイルの定義 (src/styles/typography.css)

    • Tailwind CSS を使用してタイプ別に色分け
    • ライト/ダークモードの両方に対応
    • 折りたたみ時のアニメーションも実装

この記事に表示されている callout は、すべて実際に動作している実例です。

まとめ

私が感じたこと

remark-calloutは、マークダウンに視覚的なアクセントを加えるための、シンプルで効果的なツールだと感じました。特に以下の点が印象的でした：

どんな場面で使えそうか

以下のような用途で特に有用だと思います：

個人的な感想

実際にセットアップしてテストしてみることで、プラグインがどのようにマークダウンを変換し、HTMLを生成するかを理解できたのは良かったです。特に、折りたたみ可能なコールアウトが <details> 要素として出力される仕組みは、ドキュメントを読むだけでは分からなかった発見でした。

マークダウンで書いたドキュメントの読みやすさを向上させたい方や、Obsidianユーザーで同じ記法を他のプロジェクトでも使いたい方には、ぜひ試してみることをお勧めします。

参考リンク

検証環境

本記事で使用したパッケージのバージョン：

remark-calloutを実際に試してみて、Obsidian風のコールアウトを簡単にマークダウンで実現できることが分かりました。

この記事が、マークダウンでのドキュメント作成を改善したい方の参考になれば幸いです。

Share this post on:
Share this post via WhatsAppShare this post on FacebookShare this post on XShare this post via TelegramShare this post on PinterestShare this post via email
Previous Post
人格付与
Next Post
pino-pretty を試してみた - 開発時に読みやすいログを出力する