ブログ記事にコードブロックを載せる際のマークダウン活用術
技術ブログを書く機会が増えるなかで、コードブロックの扱いひとつで読みやすさが大きく変わることを実感します。普段はWebデザインやスマートフォンアプリ制作の話題を取り上げていますが、ソースコードを提示する場面は意外と多いものです。シンプルな三連バッククォートで囲むだけでも機能はしますが、もう一歩踏み込めば読者の理解をもっと助けられます。
私自身、以前はコピペしただけのコードを載せて「これで動きます」と書いて終わりにしていました。それでは伝わらない場面が多く、説明する側の工夫が足りなかったと反省しました。読者が実際に手を動かして試す可能性を考えると、コードブロック周辺のテキスト設計は重要な要素です。
特にスマートフォンからの閲覧を意識すると、横に長いコードは折り返しやスクロールの処理が問題になります。Markdownは静的サイトとの相性が良い反面、表示制御はテーマやCSSに依存するため、書き手側で工夫できる余地が少なくありません。
本記事では、コードブロックの基本から、シンタックスハイライト、ファイル名の付与、可読性の高いレイアウト、プレビュー確認まで、実務で取り入れやすい手法を整理して紹介します。
コードブロックの基本構文を押さえる
Markdownでコードを埋め込む標準的な方法は、バッククォート三つで上下を囲むフェンス記法です。一行だけならバッククォート一つで囲むインライン記法も併用できます。言語名を指定すると、多くのレンダラがハイライトを自動で適用してくれるため、たとえば javascript や python と続けた一行で十分機能します。
フェンスの数を四つ以上にすると、特定のジェネレータや静的サイトビルダでは別の意味になることがあります。三つで統一しておくのが無難で、本文中でバッククォートを使いたい場合はバックスラッシュでエスケープする手段を知っておくと混乱を防げます。
インデントによるコードブロック記法も残っていますが、半角スペース四つ分の空白が必要で、Markdown以外の文脈にコピーすると崩れやすい弱点があります。フェンス記法に揃えておけば、エディタやプレビューツール間でも表示が安定します。
シンタックスハイライトで意図を明確にする
ハイライトは色を付ける装飾と思われがちですが、本来の役割は構造を読み手に伝える点にあります。予約語、関数名、文字列リテラル、コメントが視覚的に区別されることで、スクロールしながらでも処理の流れを追えます。私は普段、エディタではMonokaiに近い配色、ブログ側では落ち着いたパレットを採用しています。
言語の指定を間違えると意図しない色付けになることがあります。HTMLとJSX、Python 2と3のように、似た文法でも見分けが付くよう、冒頭の宣言部分まで含めて例示する習慣があります。読む側にとっても、それが何のコードか一目で分かる利点につながります。
複数行にまたがる設定ファイルやJSONの場合は、JSONやYAMLと明示するだけでも雰囲気が伝わります。テーマによっては対応していない言語もあるため、主要な記法は押さえておきたいところです。
ファイル名やタイトルを添えるひと手間
フェンスの直前に filename.js のように名前をコメントとして添える手法があります。多くの静的サイトジェネレータではこの記法がサポートされており、コードがどのファイルのものかを示せます。読者にとっては、自分のプロジェクトに組み込むときの参照が楽になります。
私はハッカソンの成果物を記事にすることが多いのですが、その際もコンポーネント名やモジュール名を添えることで、あとから自分が見直す際の手がかりになります。実例として、ハッカソン中の参考実装を整理した中でも、こうした命名ルールが後から読まれることを前提に機能していました。複数のファイルを続けて提示するときには、特に効果が出ます。
日本語のタイトルでは扱いづらい場面もあるため、半角英数字のファイル名をそのまま使う運用が無難です。設計が古い記事の表記を新しい記法に揃えるときには、過去記事との整合性も併せて確認する流れを作っています。
長いコードにはスクロールと折り返しを用意する
スマートフォンで閲覧すると、横に長い設定ファイルやテーブル定義が画面を突き抜けてしまいます。コードブロックに対して overflow-x: auto を効かせて横スクロールを許可するのが基本です。PCでは折り返し、スマートフォンではスクロールといった切り替えもCSSで実装できます。
折り返しを許可するかどうかは内容次第です。論理構造を重視するコードでは折り返しを避け、見た目や表形式のデータは折り返しても問題ない場合が多くあります。私は、可読性を優先したい場面では折り返し、参照用としての役割が強いときはスクロールと明確に決めています。
コードブロックの前後に短い説明文を置くことも、読み進めるうえで助けになります。コードだけが大きく並んでいる状態は理解の妨げになりがちで、一段落分の補足を入れるだけで印象が変わるものです。
プレビューで確認する習慣をつける
ローカルで書いた記事を公開前にプレビューする工程は、意外と後回しにされがちです。実際のレンダリングを確認し、コードブロックの位置や色が想定どおりか確かめます。私は執筆用のエディタとは別に、最終確認用のプレビュー画面を必ず開く流れにしています。
過去にはフォントや余白の設定によって、意図せずコードが小さく表示される経験をしました。文字サイズは本文と同じか、少しだけ大きくする程度が見やすいとされています。ダークテーマを好む読者も増えているため、テーマ切り替え時の見栄えも見ておきたいところです。
レイアウト崩れに気付かずに公開してしまうと、読者からの指摘で慌てて修正することにもつながります。公開前の最終チェックを習慣化すれば、こうした手間を大きく減らせます。
ここまで紹介した工夫は、特別なツールがなくても今日から始められます。コードブロックの扱いひとつで記事の質が変わるため、まずはシンタックスハイライトとファイル名の付与から試してみてください。普段の活動全般については、プロフィールページで発信を続けていますので、あわせて読んでいただけるとうれしいです。