WP Markdown to Gutenberg

マークダウンで書いた独自記法を、Gutenbergエディターへのペースト時に自動変換するWordPressプラグイン。

対応記法

コールアウトブロック（core/group）

:::vk-group-alert-info
テキスト（見出し・リスト・太字なども可）
:::

::: の後に続くタイプ文字列がそのまま is-style-{type} の className になる。ホワイトリストはなく、対応するブロックスタイルが登録されていれば任意のスタイル名を指定可能。

タイプ文字列には英字で始まる英数字・ハイフン・アンダースコア（[a-zA-Z][a-zA-Z0-9_-]*）が使用可能。

省略記法

よく使うブロックスタイルは省略記法でも指定できる。省略記法はプラグインルートの shorthand-map.json で定義されており、ビルド不要で追加・変更が可能。

:::info
テキスト
:::

• 内側のマークダウンは段落・見出し・リストなどの標準ブロックに自動変換
• 閉じタグ ::: の前にタブ・スペースがあっても認識される

省略記法の追加・変更方法

プラグインルートの shorthand-map.json を編集する。ビルド不要（ページリロードで即反映）。

{
  "callout": {
    "info": "comp-info",
    "related": "comp-related",
    "warning": "sme-alert-warning",
    "success": "sme-alert-success"
  },
  "button": {
    "blue": "comp-blue",
    "orange": "comp-orange"
  },
  "reuse": {
    "cta": 6961
  }
}

• callout：コールアウトブロック（:::type）の省略記法
• button：ボタンブロック（[btn type]）の省略記法
• キー：記法で使う省略名
• 値：適用される is-style-{値} の {値} 部分
• エントリを追加するだけで新しい省略記法が有効になる
• ファイルが存在しない・JSON が不正な場合は省略記法が無効になるだけで、フルネーム記法は正常動作する

画像ブロック（core/image）

パターン1：通常の画像

![alt テキスト](https://example.com/image.png)

外部URLをそのまま参照する画像ブロックに変換。画像はメディアライブラリへ登録されない。

パターン2：リンク付き画像

[![alt テキスト](https://example.com/image.png)](https://example.com/link)

リンク（href）付きの画像ブロックに変換。

• コールアウトブロックの内側に画像記法を書いた場合も変換される
• パターン1（^!\[）とパターン2（^\[!\[）は行頭文字が異なるため、互いに誤検知しない
• 画像記法の行頭にインデント（スペース・タブ）を入れないこと（認識されない）

パターン3：揃え指定付き

![alt テキスト](https://example.com/image.png) right

閉じ括弧の後にキーワードを追記することで画像の揃えを指定できる。

• キーワードを省略した場合は揃え指定なし（従来通り）
• リンク付き画像（[![alt](img)](link)）でも使用可能
• :::cols 内でも使用可能

メディアとテキストブロック（core/media-text）

画像とテキストを横並びに配置する「メディアとテキスト」ブロックに変換。

:::media-text
![alt テキスト](https://example.com/image.jpg)

テキスト内容（見出し・リスト・太字なども可）
:::

オプション指定

:::media-text right 40%
![alt テキスト](https://example.com/image.jpg)

テキスト内容
:::

• メディアの幅は15〜85%の間で指定できます。範囲外の値は自動的にクランプされます
• right と N% は任意の組み合わせで省略可能
• 内側のマークダウンは段落・見出し・リストなどの標準ブロックに自動変換
• リンク付き画像（[![alt](img)](link)）も使用可能。その場合、画像にリンクが設定される
• :::media-text ブロック内の最初の画像行がメディア側になり、残りのテキストがテキスト側になる

2カラム画像ブロック（core/columns / core/gallery）

画像を左右2枚並べて配置するブロックに変換。ビフォー／アフター比較や商品カット2枚を並べるケースを想定。

:::cols
![ビフォー](https://example.com/before.jpg)
![アフター](https://example.com/after.jpg)
:::

• リンク付き画像（[![alt](img)](link)）も使用可能

ボタンブロック（core/buttons > core/button）

[btn](https://example.com) ボタンテキスト
[btn outline](https://example.com) ボタンテキスト

デフォルト設定

ボタンブロックのペースト時、外側の core/buttons ブロックに以下のデフォルト設定が自動的に適用される。

出力されるHTMLの例：

<div class="wp-block-buttons has-custom-font-size has-medium-font-size is-content-justification-center is-layout-flex wp-block-buttons-is-layout-flex">
  <div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="https://example.com">ボタンテキスト</a></div>
</div>

ボタンスタイルの省略記法

コールアウトと同様、ボタンスタイルも shorthand-map.json の button セクションで省略記法を定義できる。

[btn primary](https://example.com) ボタンテキスト

shorthand-map.json に "button": { "primary": "vk-btn-primary" } と定義されていれば、上記は is-style-vk-btn-primary に展開される。

再利用ブロック（core/block）

{{reuse:42}}
{{reuse:cta}}

WordPressの再利用ブロックを呼び出す。投稿IDまたは shorthand-map.json で定義したエイリアスで指定できる。

エイリアスを使う場合は shorthand-map.json の reuse セクションにキーと投稿IDを追加する：

{
  "reuse": {
    "cta": 6961,
    "footer": 1234
  }
}

• エイリアスが shorthand-map.json に存在しない場合：
  • 再利用ブロックのみのペーストは標準ペーストにフォールバックし、テキストがそのまま挿入される
  • 他のブロックと混在している場合は未解決のブロックのみスキップされる（他のブロックは正常挿入）

続きを読む（core/more）

:::more:::

独自の :::more::: 記法を WordPress の「続きを読む」ブロック（core/more）に変換。

Visual Link Preview（visual-link-preview/link）

Visual Link Preview プラグインのブロックを生成する。

[embed](https://example.com/article)

• URLのみ指定。タイトル・サムネイル・概要はプラグインがエディター上で自動取得する
• デフォルト値: nofollow: false、new_tab: true、template: 'simple'、type: 'external'、provider_used: 'php'、image_id: -1
• Visual Link Preview プラグインが未有効の場合は core/paragraph にリンクとしてフォールバック
• ブロック変換時に情報が表示されていない（空ブロックになっている）場合は、変換後のブロックを選択状態にし、サイドバーのブロック設定を開いて「Metadata Provider」項目内 "Select provider..." と表示されているプルダウンから"Self-hosted (PHP)" を選択することで、PHP側でURLの情報を取得して表示されるようになる

ペースト位置の仕様と既存投稿の編集フロー

ペーストしたブロックの挿入位置は、カーソルがあったブロックの直後になります。

既存投稿へのマークダウン追加 — 推奨フロー

1. エディターで挿入先の直前ブロックをクリック（選択状態にする）
2. 別タブ・別アプリからマークダウンをコピー
3. WordPressエディターに戻る
4. ペースト（Ctrl+V / Cmd+V）

ブラウザがタブに戻った際、直前のブロックフォーカスが自動復元されるため、タブ切り替え後の再クリックは通常不要です。 ただし投稿を開いてまだどのブロックもクリックしていない場合は、ペースト前に一度ブロックをクリックしてください。

未実装機能

以下の記法は現在未実装です。将来のバージョンで対応予定です。

汎用ブロック挿入（吹き出し・固有ブロック等）

プラグイン固有ブロックをブロック名・属性で直接指定できる汎用記法。

{block:vk-blocks/balloon position="left" name="筆者" message="こんにちは"}

• block: に続けてGutenbergのブロック名を指定
• スペース区切りで key="value" 形式の属性を任意個指定
• 将来使用プラグインが変わっても、記法のブロック名を変えるだけで対応可能

技術メモ（実装上のハマりポイント）