技術ブログ用のWordPressブロックを自作してみた

技術記事を書いていると、毎回同じような情報を整えていることに気づきます。構成図、検証環境、設定ファイル、実行コマンド、詰まったところ、最後のまとめ。この記事では、技術ブログ向けにWordPressブロックを自作した理由と、Scyra Blocksで用意した表現用ブロックの使いどころをまとめます。

最近はn8nのQueue ModeやAWS Cost Explorer APIの記事を書きながら、こういう「技術記事の部品」をもう少し安定した見た目で置きたいと思う場面が増えていました。そこで、自分のブログ用にGutenbergブロックを追加するWordPressプラグインを作りました。

作ったもの: 技術ブログ用のWordPressブロック

作ったのは「Scyra Blocks」というWordPressプラグインです。WordPressブロックとして構成図、コード、コマンド、トラブルシュートなどを用意し、技術ブログでよく使う情報をSANGOの本文になじむカードとして扱えるようにしています。

今のところ、次の8種類のブロックを用意しています。

• 構成図: Mermaid記法でシステム構成や処理の流れを表示する
• 検証環境: OS、ランタイム、アプリケーションバージョンなどを整理する
• コードブロック: JSON、YAML、PHP、設定ファイルなどを表示する
• コマンド + 実行結果: コピー可能なコマンドと結果をまとめる
• コールアウト: 補足、注意、リスク、良い判断を記事中で強調する
• トラブルシュート: 症状、原因、確認事項、解決の方向を整理する
• 手順カード: 作業の流れや判断順を番号付きで表示する
• まとめカード: 記事末尾の要点と結論を整理する

ベースにしているのはWordPress標準のBlock Editorです。構成図はMermaid、コードの色分けはHighlight.jsを使い、記事ごとに必要な表現だけを読み込む方針にしています。

全体像を見せる: 構成図ブロック

まず欲しかったのが、記事の前半で全体像を見せるための構成図ブロックです。Mermaid記法を本文中に置くと、公開画面ではSVGとして描画されます。

flowchart LR
  Editor@{ icon: "scyra:browser", form: "rounded", label: "WordPress Editor", pos: "b", h: 52 }
  Blocks@{ icon: "scyra:plugin", form: "rounded", label: "Scyra Blocks", pos: "b", h: 52 }
  PHP@{ icon: "scyra:server", form: "rounded", label: "Dynamic Blocks / PHP", pos: "b", h: 52 }
  JS@{ icon: "scyra:code", form: "rounded", label: "Editor UI / JavaScript", pos: "b", h: 52 }
  Article@{ icon: "scyra:browser", form: "rounded", label: "Article Frontend", pos: "b", h: 52 }
  Mermaid@{ icon: "scyra:cloud", form: "circle", label: "Mermaid Diagram", pos: "b", h: 52 }
  Highlight@{ icon: "scyra:code", form: "circle", label: "Highlight.js", pos: "b", h: 52 }
  Cards@{ icon: "scyra:server", form: "rounded", label: "Readable Tech Cards", pos: "b", h: 52 }
  Editor --> Blocks
  Blocks --> PHP
  Blocks --> JS
  PHP --> Article
  Article --> Mermaid
  Article --> Highlight
  Article --> Cards

構成図は、細かい説明を読む前に「何がどこにつながっているのか」を掴んでもらうために使います。公開済みのn8n Queue Modeの記事でも、Main、Worker、Redis、PostgreSQLの関係を説明するときにかなり役立ちました。

再現条件を残す: 検証環境ブロック

技術記事では、どの環境で動かしたのかが後から効いてきます。バージョン違いで挙動が変わることもあるので、検証環境は本文とは別のカードとしてまとめるようにしました。

このブロックは、OSやDockerのバージョンだけでなく、WordPressテーマやプラグインのバージョンを書く用途にも向いています。

設定ファイルを見せる: コードブロック

コマンドと設定ファイルは、見た目を分けたいと思っていました。ターミナル風のUIはコマンドには合いますが、JSONやYAMLまで同じ見た目にすると少し違和感があります。そこで、設定ファイル用のコードブロックを追加しました。

register_block_type(
    'scyra/code-block',
    array(
        'render_callback' => 'scyra_render_code_block',
    )
);

コードブロックは、JSON、YAML、PHP、TypeScript、PowerShellなどを選べます。設定ファイル名も出せるので、記事中で「これはどのファイルに書くものなのか」が伝わりやすくなります。

手元で実行するものを見せる: コマンド + 実行結果ブロック

一方で、実際にターミナルで実行するコマンドは、コピーしやすい形で置きたいです。そこで、コマンドと実行結果をセットで表示するブロックを用意しました。

wp plugin list --status=active | grep scyranwp post get 2787 --field=post_status

scyra-blocks activen draft

このブロックは、読者がそのままコピーして試すコマンドに向いています。実行結果もセットで置けるので、期待する状態を伝えやすいです。

注意点を埋もれさせない: コールアウトブロック

記事を書いていると、本文の途中で「ここは大事」「ここは注意」「これは良い判断だった」と言いたい場面があります。そういう一言を普通の段落で書くと流れやすいので、コールアウトとして分けられるようにしました。

コールアウトは、補足、良い判断、注意、リスクの4種類を用意しています。使いすぎるとうるさくなるので、本文の流れを一度止めてでも伝えたいことにだけ使う想定です。

詰まったところを残す: トラブルシュートブロック

技術記事で一番あとから効いてくるのは、実は成功した手順よりも詰まったポイントだったりします。自分がどこで迷ったのか、何を確認したのかを残しておくと、未来の自分にも読み手にも役立ちます。

このブロックは、エラー対応だけでなく、設計上の迷いどころを整理する用途にも使えます。

作業の順番を見せる: 手順カード

実装記事では、細かいコマンドの前に「どういう順番で進めるのか」を見せた方が読みやすいことがあります。そこで、作業の流れを番号付きで整理する手順カードを作りました。

手順カードは、作業ログをそのまま貼るのではなく、読み手が迷わない順番に並べ直すためのブロックです。

最後に要点を回収する: まとめカード

最後は、記事の要点をまとめるためのカードです。普通の箇条書きでも良いのですが、記事の締めとして少しだけ目立たせることで、読み終わりの印象を整理しやすくなります。

今後やりたいこと

今後は、ブロック定義をblock.jsonに寄せたり、スクリーンショット付きのREADMEを整えたりしたいです。公開リポジトリとして見てもらうなら、インストール方法や更新手順ももう少し丁寧にした方が良さそうです。

あとは、比較表やリポジトリカードのようなブロックも面白そうです。技術記事はどうしても文章とコードが中心になりがちなので、読み手が一瞬で判断できる見せ方を少しずつ増やしていきたいです。