【入門編】Confluenceの「カスタムマクロ（User Macro）」開発入門！Velocityテンプレートを用いた社内ニッチ要件の完全自動解決法 – プロジェクト・ナレッジ管理活用バイブル

Confluenceの「カスタムマクロ（User Macro）」開発入門！Velocityテンプレートを用いた社内ニッチ要件の完全自動解決法

みなさん、こんにちは！日々の開発やプロジェクト管理、ドキュメントの整理、順調に進んでいますか？

「Confluence（コンフルエンス）は便利だけど、もう少しこういう表示形式にしたいな…」
「標準のマクロだと、社内で決まっているデザインルールや特殊なステータス管理にあと一歩届かない！」

そんなもどかしい思いをしたことはありませんか？実は、Confluenceには「ユーザーマクロ（User Macro）」という、社内特有のニッチな要件を100%思い通りに自動解決できる強力な機能が備わっています。

この記事では、まだConfluenceのカスタムマクロを触ったことがない初心者のみなさんに向けて、ユーザーマクロの仕組みから、セットアップ手順、そして実際に現場で使える美しいUIマクロの作成までを優しく丁寧に解説します。

これをマスターすれば、毎日のドキュメント作成が劇的に楽になり、チームのナレッジ共有の質が跳ね上がりますよ！一緒に一歩を踏み出してみましょう。

—

1. ユーザーマクロ（User Macro）とは？ツールの役割と魅力

まず、「ユーザーマクロって何？」という全体像から整理していきましょう。

Confluenceには「ステータス」や「パネル」「情報」といった便利な標準マクロが最初から用意されていますよね。しかし、実務では以下のような「社内特有のニッチ要件」が発生しがちです。

「障害レベルに応じた専用警告枠を、規定のコーポレートカラーで統一表示したい」
「APIの仕様書テンプレートで、特定の形式のレスポンスコードをきれいにパーツ化したい」
「ページ担当者、最終確認日、レビュー状態をセットにした『責任者カード』を上部に固定配置したい」

これらを毎回手動で装飾・整形するのは時間がかかりますし、人によってレイアウトが崩れて情報がサイロ化する原因になります。

そこで登場するのがユーザーマクロです。

【ユーザーマクロの構成要素】
［パラメータ入力フォーム］（ユーザーが文字や選択肢を入力）
↓
［Velocityテンプレート］（ロジック処理・変数展開）＋［HTML / CSS］（デザイン）
↓
［美しく統一されたUIを自動レンダリング！］

ユーザーマクロを使えば、HTML/CSSによるUIのデザインと、Javaベースの軽量テンプレートエンジンであるApache Velocity（ヴェロシティ）を組み合わせることで、独自のカスタムマクロを誰でも簡単に作成できます。一度作ってしまえば、チーム全員がボタン一つでその美しいデザインを呼び出せるようになるのです。

—

2. 準備編：ユーザーマクロの作成画面へアクセスしよう

それでは、実際のセットアップ手順を見ていきましょう。

> 💡 補足
> ユーザーマクロの作成には、Confluenceの管理者権限（Confluence Administrator）が必要です。もし権限がない場合は、この記事で紹介するコードを担当の管理者の方に共有して「これを作ってください！」と頼んでみてくださいね。

Step 1: 管理画面を開く

1. Confluence画面右上の 歯車マーク（設定アイコン） をクリックします。
2. 左側のサイドメニューから 「ユーザーマクロ (User Macros)」 を選択します。
3. 「ユーザーマクロの追加 (Add User Macro)」 ボタンをクリックします。

—

3. 基礎編：基本パラメータの設定項目を知ろう

「ユーザーマクロの追加」画面を開くと、いくつかの設定項目が並んでいます。まずは最も重要な基本項目を理解しましょう。

これで下準備は完了です！次は、実際に動作するテンプレートコードを書いていきましょう。

—

4. 実践編：HelloWorldから現場で役立つ「高機能ステータスカード」を作ろう！

今回は、初心者向けに「入力したパラメータに応じて背景色とアイコンが自動で切り替わる、美しく実用的なカードマクロ」を作成します。

まずはシンプルなHelloWorld的な発想から始め、Velocityの力を使って実用的なデザインへと仕上げていきます。

テンプレートコードの記述

「Macro Body」の入力エリアに、以下のコードをそのまま貼り付けてみてください。

@param Type:type=enum|options=info,warning,success|desc=カードの種類を選択|required=true|default=info

@param Title:type=string|desc=カードのタイトル|required=true

@param Owner:type=username|desc=担当者（ユーザー名）|required=false

================================================

1. Velocityによるロジック処理（色の切り替え）

================================================

set($cardColor = “#2563eb”)

基本青色 (info)

set($bgColor = “#eff6ff”)
set($borderColor = “#bfdbfe”)
set($icon = “ℹ️”)

if($paramType == “warning”)
#set($cardColor = “#d97706”)

警告黄色 (warning)

#set($bgColor = “#fffbeb”)
#set($borderColor = “#fde68a”)
#set($icon = “⚠️”)
elseif($paramType == “success”)
#set($cardColor = “#16a34a”)

成功緑色 (success)

#set($bgColor = “#f0fdf4”)
#set($borderColor = “#bbf7d0”)
#set($icon = “✅”)
end

================================================

2. HTML & CSS によるスタイリングとレンダリング

================================================

$icon
$webwork.htmlEncode($paramTitle)

#if($paramOwner && $paramOwner != “”)

👤 担当: $paramOwner

#end

$body

—

コードの解説（ここが本質です！）

少しコード解説をさせてくださいね。ここを押さえるとVelocityがぐっと面白くなりますよ！

① メタデータ宣言（` @param`）

先頭の `

@param` は、ユーザーがマクロを挿入する際に出てくる「入力ダイアログ」を自動生成する命令です。

`Type`: ドロップダウン（`enum`）で「info」「warning」「success」を選べるようにしています。
`Title`: テキスト入力（`string`）でタイトルを指定します。
`Owner`: Confluenceの「ユーザー指定（`username`）」フィールドを使用しています。

② Velocity変数と条件分岐（`#set`, `#if`）

Velocityでは `#set($変数名 = 値)` で変数を定義します。
`#if($paramType == “warning”)` のように、ユーザーが選んだ値に応じて背景色やアイコンを動的に切り替えています。
宣言したパラメータの値は `$paramパラメータ名` で取得できます。

③ `$body` と `$webwork.htmlEncode()`

`$body`: マクロ枠の中に書いた文章や装飾テキストがそのままここに差し込まれます。
`$webwork.htmlEncode()`: ユーザーが入力したタイトル文字列を安全にエスケープ（HTML化）し、セキュリティ（XSS対策）を高めています。

—

5. 動作確認：さっそくページで使ってみよう！

設定を保存したら、いよいよ動作確認です。

1. ページ編集画面を開く

任意のConfluenceページを開き、編集モード（キーボードの `e`）に入ります。

2. マクロの呼び出し

文章入力エリアで `/custom-notice` と入力するか、上部メニューの「＋（挿入）」から作成した「社内統一お知らせカード」を選択します。

/custom-notice ← これを打ち込むだけ！

3. パラメータの入力

ダイアログが開くので、以下のように入力してみましょう。

Type: `warning`
Title: `【重要】データベースメンテナンスのお知らせ`
Owner: ご自身のユーザー名

4. 本文の記述と保存

マクロ枠の中に「本日22:00よりメンテナンスを実施します。作業中はドキュメントの更新をお控えください。」と入力し、ページを保存（Publish）します。

—

🎨 レンダリング結果の確認

ページを保存すると…どうでしょうか！
美しく角丸にカットされ、左側にアクセントカラーの警告線が入った洗練されたカードが表示されたはずです。担当者のバッジも右上にきれいに配置されていますね。

標準マクロだけでは表現できなかった「現場が本当に欲しかったデザイン」が、わずか数分で完成しました！

—

6. プロが教える！ユーザーマクロ運用・設計のコツ

最後に、世界中のアジャイルチームで現場改善を行ってきた私から、ユーザーマクロを長期的に運用していくための3つの極意をお伝えします。

📌 1. スタイルは「インラインCSS」で完結させる

Confluenceの別CSSファイルにスタイルをまとめようとすると、Confluence本体のアラートやアップデートでクラス名がバッティングしたり、スタイルの適用漏れが発生しやすくなります。マクロ内で完結するインラインスタイル（`style=”…”`）を基本にするのが、崩れにくく保守しやすい秘訣です。

📌 2. 入力値のエスケープを怠らない

タイトルなどのテキストパラメータを受け取る際は、必ず `$webwork.htmlEncode($paramName)` を使いましょう。これにより、予期せぬHTML崩れやセキュリティリスクを防ぎ、安全な社内プラットフォームを維持できます。

📌 3. ドキュメントの「型」を標準化し、ベロシティを上げる

ユーザーマクロの最大の目的は、見た目を綺麗にすることだけではありません。
「仕様書はこのマクロを使って書く」「障害報告はこのカードで囲む」というフォーマットの標準化を実現することです。書く人の迷いが減り、読む人の理解速度が上がるため、結果として開発チーム全体のベロシティ（開発速度）が劇的に向上します。

—

7. まとめ

今回はConfluenceの「ユーザーマクロ」を使ったカスタムUIの自動化手法について解説しました。

ユーザーマクロを使えば、社内固有の要件をコードで自由に解決できる
Velocityを使えば、条件分岐や動的な色の変更も思いのまま
フォーマットが統一されることで、チーム全体のナレッジ共有効率が爆発的に上がる

ツールに自分たちの運用を合わせるのではなく、ツールを自分たちの理想に合わせて手懐ける。これこそが、強い開発チームを作る第一歩です。

まずは小さな「お知らせカード」から作成してみて、チームのみんなを「おっ、これ見やすくていいね！」と驚かせてみませんか？

もし実装で困ったことがあれば、いつでも聞いてくださいね。応援しています！