Qiita記事のコードブロックの見せ方｜言語指定・差分・実行結果でグッと読みやすくする

はじめに

技術記事の価値は、文章の巧みさよりも「コードがどれだけ読者に伝わるか」で決まることが多いです。同じ内容でも、コードブロックの見せ方ひとつで「すぐ試せる記事」にも「結局よくわからない記事」にもなります。

この記事では、Qiitaのコードブロックを読者にとって読みやすくするための具体的な技法を整理します。扱うのは次の5点です。

• 言語指定（シンタックスハイライト）の効果
• 長いコードの畳み方・分割の考え方
• 差分（diff）の見せ方
• 実行結果の併記
• コピペで動く最小例の価値

いずれも特別なツールは不要で、標準のMarkdown記法とQiitaが許可するHTML（折りたたみ用の details）だけで実現できます。

言語指定でシンタックスハイライトを効かせる

コードブロックはバッククォート3つで囲みますが、開始行の直後に言語名を書くとシンタックスハイライトが効きます。

```python
def greet(name):
    return f"Hello, {name}"
```

言語を指定すると、キーワード・文字列・コメントが色分けされ、構造が一目で追えるようになります。逆に言語を省略すると、ただのモノスペース文字列として表示され、読者は脳内でパースする負担を負います。

言語指定のちょっとしたコツです。

• シェルのコマンドは bash、設定ファイルは yaml json toml など、内容に正確な言語名を選ぶ
• 出力ログやプレーンな貼り付けは text（plaintext）を指定すると、無関係な単語が色付けされる誤ハイライトを避けられる
• QiitaのハイライトはRougeを使っており、言語名が対応リストにないと色が付かないので、ハイライトされない時はまずスペルと別名（エイリアス）を疑う

なお、```python:greet.py のように 言語名:ファイル名 と書くと、ブロックの上にファイル名を表示できます。どのファイルのコードかを示したいときに便利です。

「とりあえず三連バッククォートで囲む」で止めず、必ず言語名を添える習慣をつけるだけで、記事の読みやすさは大きく変わります。

長いコードは「畳む」か「切る」

数十行を超えるコードをそのまま貼ると、読者はスクロールに埋もれて要点を見失います。長さへの対処は大きく2方向あります。

ひとつは折りたたみです。Qiitaの本文はHTMLの details タグが使えるので、補足的な全文や設定ファイルを畳んでおけます。

ここで重要な注意点があります。details の中にコードブロックなど（空行を含むMarkdown）を入れるときは、中身を <div> で囲み、<div> とコードブロックの間に空行を入れる必要があります。これを省くと正しくレンダリングされません。

<details><summary>全文を見る</summary><div>

```python
# ここにコードブロック
print("hello")
```

</div></details>

summary に「全文」「ログ全体」など中身がわかる見出しを書いておくと、開く前から内容が予想できて親切です。最初から開いた状態にしたいときは <details open> と書きます。

もうひとつは分割です。記事の流れに合わせてコードを意味のある単位で切り、各ブロックの前後に「ここで何をしているか」を1〜2文で添えます。

• 関心ごと（設定／処理本体／呼び出し）ごとにブロックを分ける
• 変更に関係ない定型部分は # 省略 のようなコメントで割愛する
• 行が長くて横スクロールになる場合は、変数に分けるなどして1行を短くする

「全部見せる」ことより「読者が追える単位で見せる」ことを優先すると、長いコードでも理解の負担が減ります。

差分は diff で意図を伝える

「この行をこう直す」という変更を説明するとき、修正前後の2つのブロックを並べるより、diff 指定が有効です。

```diff
 function add(a, b) {
-  return a - b;
+  return a + b;
 }
```

diff を指定すると、先頭が - の行は削除（赤系）、+ の行は追加（緑系）として色分けされ、変わった箇所が瞬時にわかります。書くときの注意点です。

• 変更しない行は先頭に半角スペースを1つ入れる（文脈行として扱われる）
• - + は行頭に置く。インデントはその後ろに続ける
• 前後数行だけ文脈として残し、無関係な部分は載せない

さらにQiitaには、差分と言語のシンタックスハイライトを同時に効かせる記法があります。diff_言語名（例: ```diff_javascript）と書くと、+/- の差分色分けに加えて、コード自体も指定言語として色付けされます。差分を見せつつ構文も読みやすくしたいときに便利です。

差分が主役の解説（バグ修正、リファクタ、設定変更など）では、diff で見せると「どこが論点か」が説明なしで伝わります。一方、コード全体を理解してほしい場面では通常の言語指定の方が読みやすいので、目的で使い分けます。

実行結果を併記して「動いた証拠」を見せる

コードだけを示して結果を書かないと、読者は「本当にこう動くのか」を確かめられません。コードの直後に実行結果を別ブロックで添えると、記事の信頼性が一段上がります。

例えばコマンドと出力をセットで見せます。

$ python -c "print(2 ** 10)"

1024

併記のポイントです。

• 入力（コマンド／コード）と出力（結果）はブロックを分け、出力側は text にする
• 出力が長い場合は要点の数行だけ残し、... で省略を明示する
• エラーを再現する記事なら、エラーメッセージも実際の出力をそのまま貼る（読者が同じメッセージで検索して辿り着きやすくなる）

「コード → 結果」の対が並んでいると、読者は手を動かす前に挙動を予測でき、写経のハードルが下がります。

コピペで動く最小例の価値

記事中のコードで最も価値が高いのは、コピペすればそのまま動く最小の例です。これは Minimal Reproducible Example（最小再現例）の考え方そのもので、質問サイトだけでなく解説記事でも有効です。

最小例を作るときに意識することです。

• 余計な依存やオプションを削り、本題に必要な行だけにする
• import や必要なバージョン前提を省略しない（動かすのに不可欠な情報は残す）
• 抜粋した一部だけを貼ると、読者の手元で動かず混乱を招くため、動く単位で切り出す
• 可能なら自分の環境で一度貼り直して実行し、動くことを確認してから載せる

「短く、かつ単体で動く」を両立させるのは手間がかかりますが、ここを丁寧にやった記事は読者が実際に試しやすく、結果として伝わる記事になります。

まとめ

コードブロックの見せ方は、標準のMarkdownとわずかなHTMLだけでここまで改善できます。

• 言語指定でシンタックスハイライトを効かせ、出力は text を使う
• 長いコードは details（中身は <div> で囲み空行を入れる）で畳むか、意味の単位で分割する
• 変更の説明は diff で論点を色分けして伝える（言語も効かせたいなら diff_言語名）
• 実行結果を別ブロックで併記し、動いた証拠を見せる
• コピペで動く最小例を、できれば自分で確認してから載せる

どれも一手間ですが、読者が「読む」だけでなく「試せる」記事になります。次に記事を書くときは、貼り付けたコードブロックを読者の視点で一度見直し、言語指定・差分・実行結果が適切に使えているか確かめてみてください。