Markdown コードブロック: 読みやすいコード例を崩さず載せる方法
コード例が読みにくい記事は、それだけで理解コストが一気に上がります。Markdown のコードブロックは簡単に始められますが、閉じ忘れや言語タグ不足で壊れやすいのも事実です。
Quick answer
複数行コードは三連バッククォートで囲み、必要なら言語タグを付けます。下書きは Markdown Editor で作り、公開前に Markdown Preview で見た目とコピーしやすさを確認してください。
チェックリスト中心の文書なら Markdown Checklist、構文全体を横断したいなら Markdown Editing Syntax Hub も役立ちます。
コードブロックは構文より運用が大事
よくある崩れ方はだいたい決まっています。
- 閉じバッククォートを忘れる
- 言語タグを付けずに可読性を落とす
- 長いコードをプレビューせず、そのまま公開する
書く、ラベルを付ける、表示を確認する。この 3 つを分けるだけでかなり安定します。
Workflow map
最低限必要な構文
```js
console.log("Hello, Markdown");
```
これで複数行コードを安全に載せられます。言語タグがあると、対応レンダラーではシンタックスハイライトも効きます。
言語タグを付ける意味
タグなしでも表示はできますが、読む速さが変わります。
type PublishState = "draft" | "review" | "live";
function canPublish(state: PublishState) {
return state === "review";
}
関数名、文字列、キーワードが区別されるだけで、記事の理解しやすさはかなり上がります。技術記事なら、これは装飾ではなく可読性の一部です。
実務フローの例
たとえばフロントエンド向けの更新情報を書くなら、次の流れが安定します。
- まず本文を整理する
- Markdown Editor にコード例を貼る
- 言語タグを付ける
- Markdown Preview で折り返しと視認性を確認する
公開後に「モバイルで読みにくい」「どこまでがコードかわからない」と気づくよりずっと安全です。
よくあるミスと直し方
ミス 1: 閉じフェンスを忘れる
壊れた例:
```python
def deploy():
return "running"
この状態だと、後続の本文までコードとして扱われることがあります。
修正版:
```python
def deploy():
return "running"
```
ミス 2: 言語タグを省略する
これは有効です。
```
SELECT * FROM posts;
```
ただし、こちらのほうが読みやすくなります。
SELECT * FROM posts;
インラインコードで十分な場面
npm run build や app/config.ts のような短い要素ならインラインコードで十分です。
次の条件に当てはまるならブロック化してください。
- 複数行になる
- インデントが重要
- 読者がコピーする可能性が高い
- 強調表示が理解に効く
もし内容が実行コードではなくタスク手順なら、Markdown Checklist のほうが適切です。
プレビューが効く場面
Markdown Preview が特に役立つのは、次のときです。
- 長いコードが狭い画面で読めるか見たい
- 段落の間に挟んだときの見た目を見たい
- シンタックスハイライトが過不足ないか確認したい
- コピペしやすい形かを公開前に確かめたい
Final takeaway
Markdown コードブロックは、ただ囲むだけでなく、ラベル付けとプレビューまで含めて運用すると崩れにくくなります。
Markdown Editor で 1 つコードブロックを書き、Markdown Preview で公開前の見え方まで確認してください。
Internal workflow links
- 構文の導線: Markdown Editing Syntax Hub
- タスク表現: Markdown Checklist
- 表示確認: Markdown Preview
FAQ
Markdown でコードブロックを作るには？
三連バッククォートでコードを囲みます。
シンタックスハイライトを付けるには？
開始フェンスの直後に js や python のような言語名を書きます。
コードブロックが壊れる原因は何ですか？
閉じフェンスの欠落、バッククォート数の不一致、プレビュー未確認が典型的な原因です。Markdown Preview で公開前に確認してください。