ブログにコード例を載せたいのに見た目や安全性で悩んでいませんか。
そのまま貼ると表示崩れやXSSの危険、行番号やハイライトの不足で読者に伝わりにくくなります。
この記事ではプラグインを使う方法と不要で実装する具体手順、外部サービス活用のメリットと注意点をわかりやすく解説します。
preとcode、GutenbergやClassicエディタでの貼り方、代表的なハイライトプラグイン、GitHub Gistなど外部埋め込み、そしてXSS対策までカバーします。
まずは目的整理から始める手順を本文で順を追って確認していきましょう。
WordPressにソースコードを埋め込む手順と注意点
この記事では、WordPressにソースコードを安全かつ見やすく埋め込む手順と注意点をまとめます。
実務で使える具体的な方法を中心に、プラグイン不要の手順やエディタ別のコツを紹介します。
埋め込み前の目的整理
まずは何のためにコードを載せるのかを明確にしてください。
目的によって、見せ方や必要な機能が変わります。
- 可読性の向上
- シンタックスハイライト
- 実行サンプルの提示
- 学習用の解説
例えば学習用であれば行番号やハイライトが有用です。
配布目的であればコピー機能の実装を優先すると良いでしょう。
エスケープ処理
HTMLとして誤解釈されないよう、必ずエスケープ処理を行ってください。
特に小なり記号やアンパサンドはそのまま貼ると表示が崩れます。
エディタにより自動変換される場合があるので、該当する設定を確認してください。
PHPやHTMLのサンプルを載せる際は、< と > を置き換えるか、適切な関数で処理してください。
preタグとcodeタグ
preタグは改行や空白をそのまま表示する用途で、codeタグはインラインやブロックを示す用途です。
両者を組み合わせることで可読性を保ちながらセマンティクスを示せます。
| タグ | 用途 |
|---|---|
| pre | 改行と空白を保持するブロック表示 |
| code | コードを示すインラインまたはブロック |
| pre + code | 構造を保ったコードブロック |
スタイルはテーマやCSSで整えると見栄えが良くなります。
アクセシビリティのため、適切な言語属性を付与することも検討してください。
Gutenbergコードブロック
Gutenbergには標準でコードブロックが用意されています。
ここではそのまま貼り付けるだけでエスケープ処理が行われるため手軽です。
複数言語のハイライトが必要な場合は、ブロックに言語を設定できるプラグインと組み合わせると便利です。
ブロックごとにクラスを付けられるため、後からカスタムCSSで見た目を整えやすいです。
Classicエディタでの貼り付け
Classicエディタではビジュアル表示とテキスト表示の切り替えに注意してください。
ビジュアルモードのまま貼るとHTMLが壊れる場合があるため、テキストモードを使うことを推奨します。
テキストモードでpreとcodeを明示すれば、テーマのCSSが適用されて整って表示されます。
貼り付け後は不要な自動挿入タグがないかを確認してください。
プレビューと表示確認
編集後は必ずプレビューで表示を確認してください。
PCだけでなくスマホやタブレットでの見え方もチェックすることが重要です。
改行や折り返し、フォントサイズによる可読性低下がないかを重点的に見てください。
必要であればカスタムCSSを微調整して、スクロールや横スクロールの発生を抑えてください。
最終的には実際の投稿で表示確認を行い、ユーザー視点での読みやすさを確保しましょう。
プラグインを使う実装パターン
WordPressでソースコードを美しく、かつ安全に表示するにはプラグインの利用が便利です。
プラグインは導入が簡単で、シンタックスハイライトや行番号、コピー機能などを手早く追加できます。
ただし、選定を誤ると表示崩れやパフォーマンス低下につながるため、用途に合わせて慎重に選ぶ必要があります。
Highlighting Code Block
Highlighting Code Blockは軽量で導入が簡単なプラグインです。
多くはPrismやHighlight.jsなど既存のハイライターと組み合わせて動作します。
言語の自動検出や手動指定が可能で、ブロックエディタとも互換性があります。
行番号やテーマ変更、折り返し設定が用意されていることが多く、カスタマイズの自由度が高いです。
利点は導入が速く、テーマに与える影響が小さい点です。
注意点は、プラグインごとにサポートする言語やオプションが異なる点です。
複数のハイライターを同時に読み込むと衝突する可能性があるので、不要なスクリプトは無効にしてください。
SyntaxHighlighter Evolved
長年使われている定番のプラグインがSyntaxHighlighter Evolvedです。
豊富なテーマと安定した表示で、古い環境でも動作する実績があります。
| 特徴 | 備考 |
|---|---|
| 多数のテーマ | カスタマイズ可能 |
| ショートコード対応 | Classic向け |
| 安定した動作 | 実績あり |
ショートコードでの埋め込みが主な方式なので、Classicエディタとの相性が良いです。
ただし最近はGutenbergネイティブのブロックに比べて扱いにくい場面が出てきます。
更新頻度と互換性を確認してから導入することをおすすめします。
PrismJSプラグイン
PrismJSを利用するプラグインは軽量でカスタム性が高い点が魅力です。
プラグインによって追加できる機能が異なるため、目的別に選ぶと良いです。
- 軽量
- カスタマイズしやすい
- モジュール式の拡張
- テーマ切替可能
プラグイン版は必要なモジュールだけを読み込める設計が多く、読み込みの最適化に役立ちます。
ただし、独自スクリプトや他のハイライトと併用するとスタイル衝突が起きることがあります。
Enlighter
Enlighterは視覚的に洗練されたハイライトを提供するプラグインです。
テーマの種類が豊富で、読みやすさにこだわったデザインが多いです。
Gutenbergブロックとしても使えるため、編集体験がスムーズです。
行番号や行ハイライト、カスタムフォントの指定など、細かな表示設定が可能です。
パフォーマンス面でも比較的軽く、キャッシュとの相性も良好です。
ただしプラグインの設定項目が多めなので、最初は設定に戸惑うことがあるかもしれません。
WP-Syntax
WP-Syntaxはシンプルさを重視するサイトに向く古典的なプラグインです。
導入が容易で、最低限の機能で済む場合には最適です。
軽量で基本的なシンタックスハイライトを実現しますが、最新の言語対応が限定的な場合があります。
アップデート状況やメンテナンスの有無を確認した上で採用を検討してください。
多機能なプラグインと併用するよりも、目的を絞って単独で使うのが向いています。
最後に、どのプラグインを選ぶ場合でもテスト環境で表示確認を行ってください。
実際のテーマや他のプラグインとの相性は導入後にしか分からない点が多いです。
更新頻度やセキュリティ対応、カスタマイズのしやすさを基準に選ぶと失敗が少なくなります。
プラグイン不要で埋め込む具体手順
まずはプラグインを使わずにソースコードを見栄え良く、安全に表示する方法を順を追って説明いたします。
ここではエスケープ、HTMLタグの使い方、スタイル調整、行番号やコピー機能の付与までを扱います。
HTMLエディタのエスケープ
エディタに直接コードを書き込む場合は、まず特定の記号をエスケープする必要があります。
例えば「<」や「>」はそのまま書くとHTMLとして解釈されますので、エンティティに変換するかエディタの生HTMLモードで適切に扱ってください。
WordPressでは投稿画面のテキストモードやHTMLブロックを利用すると、意図せぬ変換を避けやすくなります。
PHPやテンプレート側で出力する場合は、esc_htmlやesc_textareaなどの関数で安全に表示してください。
pre・codeの活用
ソースコードは意味的にpreタグとcodeタグで囲むのが基本です。
preは改行やインデントを保持し、codeは語彙的にコードであることを示しますので、両者を組み合わせて使うとアクセシビリティが高まります。
言語を指定したい場合はcodeタグにclass属性で言語名を付与すると、後でCSSやスクリプトで扱いやすくなります。
例としては class=”language-javascript” のようにしておくと、外部のハイライト処理に接続しやすくなります。
カスタムCSSによる装飾
見た目を整えるには専用のCSSを用意すると効果的です。
背景色、枠線、フォント、パディングなどを指定すると可読性が上がります。
水平スクロールが発生する場合は、横スクロールを許可する設定を入れて画面崩れを防いでください。
以下のようなスタイルを例として用意すると、汎用的に使いやすくなります。
.code-block {
background: #f7f7f9;
border: 1px solid #e1e1e8;
padding: 12px;
font-family: Menlo, Monaco, "Courier New", monospace;
overflow-x: auto;
border-radius: 6px;
}このような基本スタイルに、テーマの色やフォントサイズを合わせるだけで違和感が減ります。
行番号とハイライトの実装
行番号や特定行のハイライトはCSSだけで実装する方法と、少しのJavaScriptを使う方法があります。
運用コストやブラウザ対応を考えて、適切な実装を選んでください。
| 方法 | 特徴 |
|---|---|
| CSSのみ | 疑似要素で行番号を表示 |
| JavaScriptで生成 | 動的にハイライト可能 |
| サーバーで行付与 | 軽量で安定 |
CSSだけで行番号を付ける場合は、行をspanで分割するか、CSSカウンタを応用しますが、改行の取り扱いに注意が必要です。
特定行をハイライトする場合は、対象行にクラスを付けて背景色を変えるのがシンプルで分かりやすいです。
コピー機能の追加
ユーザーがコードを簡単にコピーできると、利用体験が向上します。
小さなボタンを右上に配置して、クリックでクリップボードにコピーするのが一般的です。
- ボタンを設置
- コードを選択してコピー
- 操作フィードバックを表示
実装はnavigator.clipboard APIを利用するとシンプルで信頼性が高いです。
また、コピー後に「コピーしました」と短くフィードバックを出すだけで、ユーザーの安心感が増します。
長文コードの折り返し管理
長い行があるときは折り返すかスクロールさせるかを方針として決めてください。
折り返しは可読性が上がる一方で、インデントが崩れる場合がありますので注意が必要です。
スクロール方式にすると、行ごとの構造が保たれますのでコピー時に意図した形を維持しやすくなります。
また、長文を表示する際は高さ制限を設けて「もっと見る」ボタンで展開する実装も有効です。
ユーザーがスマホで見たときの挙動も確認して、横スクロールが必要な場合は操作しやすいUIにしておくと親切です。
外部サービスを利用した埋め込み方法
外部サービスを使うと、手軽に見栄えの良いコード表示やライブデモを埋め込むことができます。
各サービスは用途や制約が異なりますので、目的に合わせて選ぶことが重要です。
GitHub Gist
GitHub Gistはコードスニペットを共有するのに便利なサービスです。
Gistを作成すると生成される埋め込み用のscriptタグを、WordPressのカスタムHTMLブロックに貼り付けるだけで表示できます。
この方法だとGist側で内容を更新すれば、埋め込んだページにも自動で反映されます。
注意点として、Gistは外部のJavaScriptを読み込むため、サイトの読み込みやセキュリティポリシーに影響する場合があります。
また、テーマのスタイルとGistのスタイルが競合して見た目が崩れることがあるので、必要に応じてカスタムCSSで調整してください。
公開したくないコードや認証情報はGistに置かないよう管理にご注意ください。
CodePen
CodePenはHTML、CSS、JavaScriptのライブデモを作るのに向いているサービスです。
埋め込み用のiframeやスクリプトが簡単に取得でき、ページ上で動くサンプルをそのまま見せられます。
フロントエンドの挙動を示したい記事やチュートリアルに特に有用です。
- 埋め込みウィジェット
- 表示モード選択
- 編集可能プレビュー
- レスポンシブ設定
公開ペンを埋め込む場合は、パフォーマンス観点から必要なリソースのみ読み込む設定を検討してください。
また、埋め込みが多いページは初回表示で読み込み負荷が高くなるため、遅延読み込みを活用することをおすすめします。
Carbon
Carbonはコードを美しい画像に変換するツールで、SNSやドキュメントでの共有に適しています。
カラーテーマやフォント、ウィンドウの有無などを細かく設定してPNGやSVGでエクスポートできます。
画像として扱うため、ユーザーがコードを選択してコピーすることはできません。
アクセシビリティを確保するためには、適切な代替テキストやテキスト版のコードを別途用意することが重要です。
また、長いコードは画像にしてしまうと視認性が落ちるので、主要な抜粋だけを使う運用が望ましいです。
jsDelivr
jsDelivrはGitHubやnpmのファイルを高速に配信するパブリックCDNです。
静的アセットとしてJavaScriptやCSSを外部から直接読み込ませたい場合に便利です。
| 用途 | 特徴 |
|---|---|
| ライブラリ配信 | キャッシュと高速配信 |
| 静的アセット配信 | バージョン指定が簡単 |
| プロトタイプ共有 | 即時反映が可能 |
jsDelivr経由で配信するとCDNキャッシュの恩恵が得られますが、URLの構成やバージョン指定に注意が必要です。
公開リポジトリであれば簡単に利用できますが、プライベートなファイルを配信する用途には向いていません。
また、外部CDNに依存するため、可用性やプライバシーの観点から運用ポリシーを決めておくことをおすすめします。
GitHub Raw
raw.githubusercontent.comはGitHubリポジトリのファイルを生のまま取得できるURLを提供します。
小さなテキストファイルやコードをサーバー経由でフェッチして表示する用途には使えます。
ただし、直接ブラウザに読み込ませるとContent-TypeやCORSの制約で期待通りに動作しないことがあります。
そのため、クライアント側で直接読み込む場合はCORSポリシーを確認し、必要ならサーバーサイドでプロキシする方法を検討してください。
また、rawリンクは公開リポジトリの内容をそのまま晒すことになるため、機密情報の管理には細心の注意が必要です。
安全かつ安定した配信が必要なら、rawを直接使わずjsDelivrなどのCDNを間に挟む方法を推奨します。
セキュリティと表示上の落とし穴
コードをそのまま貼ると見た目の問題だけでなく、セキュリティ上のリスクも発生します。
ここではよくある落とし穴を挙げつつ、安全に表示するための実践的な対処法を紹介します。
XSS対策
外部から得た文字列をそのまま出力するとクロスサイトスクリプティングの原因になります。
WordPressでは出力時に適切なエスケープ関数を使うことが基本です。
- esc_html
- esc_attr
- esc_textarea
- wp_kses
- sanitize_text_field
また、ユーザーが投稿できる場所にコードを貼る場合は許可するタグのホワイトリストを明確にしましょう。
JavaScriptやイベントハンドラを含む属性は除外して、可能ならばプレーンテキストとして扱うことを推奨します。
HTMLエンティティ化
コードをそのままHTMLに書くとブラウザが解釈してしまうため、必ずエンティティ化して表示します。
PHPならば htmlspecialchars や esc_html を使って、< と > を < と > に変換してください。
二重エンコードに注意する必要があります、既にエンティティ化された文字列を再度処理すると表示がおかしくなります。
Gutenbergやエディタの挙動によっては自動で変換される場合があるため、プレビューで必ず確認してください。
外部スクリプトの信頼性
ハイライトライブラリやコピー機能を外部CDNで読み込むと便利ですが、信頼性の検証が欠かせません。
SRI（サブリソースインテグリティ）を使ってファイルの改ざんを検出することができます。
バージョン固定で運用し、不要なときは読み込みをやめる設計にしてください。
可能であれば自ホスティングに切り替えると、外部障害の影響を減らせます。
コンテンツセキュリティポリシー
Content Security Policy を適切に設定すると、外部スクリプトやインライン実行を制御できます。
開発段階と本番でポリシーを分けてテストし、最小権限での許可に留めてください。
| Directive | Purpose |
|---|---|
| default-src | フォールバックソースの制御 |
| script-src | スクリプト読み込みの制限 |
| style-src | スタイルシートの制限 |
| img-src | 画像の読み込み制限 |
ヘッダやメタタグでCSPを配信できますが、複雑なポリシーは表示崩れを招くので段階的に導入してください。
コード埋め込み自体はテキスト中心ですが、スクリーンショットや埋め込みファイルがあるとページが重くなりがちです。
画像は適切なフォーマットで圧縮し、可能ならばWebPなどの近代フォーマットを採用してください。
大きな外部ファイルは遅延読み込みを検討して、初回表示を速く保つことが重要です。
パフォーマンス監視ツールでページ速度を定期的にチェックし、必要に応じて最適化を続けてください。
公開後の運用チェックと改善指標
公開後は表示や機能を定期的にチェックして、ユーザー体験を維持します。
具体的にはパフォーマンス、可読性、ユーザーの操作ログ、そしてセキュリティの観点で指標を追いかけると良いです。
数値化しやすいKPIを設定すると改善が進めやすく、週次や月次でレビューする運用がおすすめです。
- 表示速度（LCP, FCP）
- コードブロックの読み込み成功率
- コピー機能の利用回数
- 平均滞在時間とスクロール深度
- ページ内離脱率
- セキュリティログとスクリプトエラー検知
これらの結果を元に優先度をつけて、小さな改善を継続的に回すことが長期的な品質向上につながります。