マークダウンのコードブロックの書き方｜シンプルな使い方から便利なテクニックまで

Web

「マークダウンでプログラムのサンプルを載せたいけど、どう書くの？」
「コードに色をつけて見やすくするには？」

マークダウン（Markdown）はブログやGitHubのREADMEなどでよく使われる軽量マークアップ記法です。

とてもシンプルに文章を装飾できますが、**コードブロック（ソースコードをきれいに表示する機能）**を使いこなすと、技術記事やメモがぐっと読みやすくなります。

この記事では、マークダウンでコードブロックを作る基本の書き方、シンタックスハイライト（色分け）をする方法、ワンポイントで使える便利なテクニックを初心者向けにわかりやすく解説します。

スポンサーリンク

コードブロックとは何か

コードブロックの役割

コードブロックは、プログラムのソースコードやコマンドライン操作などを、通常のテキストと区別して表示するための機能です。

通常のテキストとの違い

通常のテキスト： これは普通の文章です。console.log(“Hello World”);というコードが混在しています。

コードブロック使用： これは普通の文章です。以下がJavaScriptのコードです：

console.log("Hello World");

この違いにより、どこがコードなのかが一目で分かるようになります。

基本的なコードブロックの書き方

方法1：3つのバッククォート（“`）で囲む

最も一般的な書き方

```
console.log("Hello World");
const name = "太郎";
```

表示結果

console.log("Hello World");
const name = "太郎";

この方法のメリット

  • 簡単：3つの記号で囲むだけ
  • 視覚的：どこがコードか一目瞭然
  • 対応範囲が広い：ほぼすべてのマークダウンエディタで対応
  • 複数行対応：何行でもOK

方法2：インデント（4スペース）を使う

従来の書き方

    console.log("Hello World");
    const name = "太郎";

各行の最初に4つの半角スペースを入れることで、コードブロックとして認識されます。

この方法の注意点

  • 推奨されない：現在はあまり使われない
  • 混乱しやすい：スペースの数を間違えやすい
  • ネストが困難：リストの中でコードブロックを使うときに問題
  • 見た目が分かりにくい：どこまでがコードか判断が難しい

方法3：インラインコード（1つのバッククォート）

文中でコードを表示

JavaScriptの`console.log()`関数を使って出力します。

表示結果

JavaScriptのconsole.log()関数を使って出力します。

使い分け

  • インラインコード：文章中の短いコード片
  • コードブロック：複数行の長いコード

シンタックスハイライト（色分け）の使い方

言語名を指定する方法

バッククォートの直後に言語名を書くことで、その言語に応じた色分けが適用されます。

JavaScript の例

```javascript
function greet(name) {
    console.log("Hello, " + name + "!");
    return "Welcome!";
}

greet("太郎");
```

表示結果

function greet(name) {
    console.log("Hello, " + name + "!");
    return "Welcome!";
}

greet("太郎");

Python の例

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

greet("太郎")
```

表示結果

def greet(name):
    print(f"Hello, {name}!")
    return "Welcome!"

greet("太郎")

主要なプログラミング言語の指定方法

言語指定名例
JavaScriptjavascript, js“`javascript
Pythonpython, py“`python
Javajava“`java
C++cpp, c++“`cpp
C#csharp, cs“`csharp
PHPphp“`php
Rubyruby, rb“`ruby
Gogo“`go
Rustrust“`rust
Swiftswift“`swift

マークアップ言語とデータ形式

言語・形式指定名用途
HTMLhtmlWebページの構造
CSScssスタイルシート
XMLxmlデータ交換
JSONjsonデータ形式
YAMLyaml, yml設定ファイル
Markdownmarkdown, md文書作成

シェル・コマンドライン

種類指定名説明
Bashbash, shUnix/Linuxのシェル
PowerShellpowershell, ps1Windowsのシェル
Command Promptcmd, batchWindowsのコマンドプロンプト
SQLsqlデータベース言語

実用的なコードブロックの例

Web開発のコード例

HTML + CSS + JavaScript

```html
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>サンプルページ</title>
    <style>
        .button {
            background-color: #007bff;
            color: white;
            padding: 10px 20px;
            border: none;
            border-radius: 5px;
        }
    </style>
</head>
<body>
    <h1>こんにちは！</h1>
    <button class="button" onclick="showMessage()">クリック</button>
    
    <script>
        function showMessage() {
            alert("ボタンがクリックされました！");
        }
    </script>
</body>
</html>
```

React コンポーネント

```jsx
import React, { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h2>カウンター: {count}</h2>
      <button onClick={() => setCount(count + 1)}>
        +1
      </button>
      <button onClick={() => setCount(count - 1)}>
        -1
      </button>
    </div>
  );
}

export default Counter;
```

データベース関連

SQL クエリ

```sql
-- ユーザーテーブルから東京在住の顧客を検索
SELECT 
    user_id,
    name,
    email,
    created_at
FROM users 
WHERE 
    prefecture = '東京都' 
    AND status = 'active'
ORDER BY created_at DESC
LIMIT 10;
```

設定ファイルの例

JSON 設定

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "サンプルプロジェクト",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest",
    "build": "webpack"
  },
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "^4.17.21"
  }
}
```

YAML 設定

```yaml
# Docker Compose 設定ファイル
version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
  
  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: myapp
    ports:
      - "3306:3306"
```

高度なテクニックと応用

複雑なコードブロックの書き方

コードブロック内にバッククォートを含める

通常の3つのバッククォートでは、内部にバッククォートが含まれるとうまく動作しません。

問題のある例：

```
const markdown = `
```javascript
console.log("Hello");
```
`;
```

解決方法：4つ以上のバッククォートを使用

````
const markdown = `
```javascript
console.log("Hello");
```
`;
````

ファイル名やタイトルを付ける

一部のマークダウンエディタでは、言語名の後にファイル名を指定できます：

```javascript:app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(3000);
```

行番号を表示する

一部のプラットフォーム（GitHubなど）では、長いコードに自動的に行番号が表示されます：

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# フィボナッチ数列の最初の10項を表示
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")
```

差分（diff）の表示

変更点を示すときに便利なdiff形式：

```diff
  function greet(name) {
-   console.log("Hello " + name);
+   console.log(`Hello ${name}!`);
  }
```

表示結果：

  function greet(name) {
-   console.log("Hello " + name);
+   console.log(`Hello ${name}!`);
  }

プラットフォーム別の対応状況

GitHub

  • 対応言語：ほぼすべての主要言語
  • 特別な機能：自動リンク、行番号表示
  • ファイル名表示：対応（一部）

Qiita

  • 対応言語：豊富な言語サポート
  • 特別な機能：コピーボタン、行番号
  • ファイル名表示：対応

Zenn

  • 対応言語：主要言語に対応
  • 特別な機能：コピーボタン、ダークモード対応
  • カスタマイズ：豊富なテーマ

VS Code

  • 拡張機能：Markdown Preview Enhanced
  • 対応言語：エディタ内の全言語
  • プレビュー：リアルタイム表示

その他のエディタ

Notion

```javascript
// Notionでもシンタックスハイライト対応
const message = "Hello Notion!";


#### Obsidian

- プラグインで機能拡張可能
- 独自のシンタックスも利用可能

## コードブロックの見た目をカスタマイズ

### CSSでのスタイリング

自分のWebサイトでマークダウンを使う場合、CSSでコードブロックの見た目をカスタマイズできます：

```css
/* コードブロックの基本スタイル */
pre {
    background-color: #f6f8fa;
    border-radius: 6px;
    padding: 16px;
    overflow-x: auto;
    font-family: 'Courier New', monospace;
}

/* インラインコードのスタイル */
code {
    background-color: #f3f4f6;
    padding: 2px 4px;
    border-radius: 3px;
    font-family: 'Courier New', monospace;
    font-size: 0.9em;
}

/* シンタックスハイライトのカスタマイズ */
.hljs-keyword {
    color: #d73a49;
    font-weight: bold;
}

.hljs-string {
    color: #032f62;
}

よくあるトラブルと解決方法

問題1：シンタックスハイライトが効かない

原因と解決方法

原因：言語名の指定ミス

  • ❌ Javascript（大文字）
  • ✅ javascript（小文字）

原因：未対応の言語名

  • ❌ nodejs
  • ✅ javascript

問題2：コードブロックが正しく表示されない

バッククォートの数が足りない

``
console.log("これは正しく表示されません");
``

正しくは3つ以上：

```
console.log("これは正しく表示されます");
```

文字化け問題

原因：文字エンコーディングの問題 解決：ファイルをUTF-8で保存

問題3：インラインコードが機能しない

バッククォートの前後にスペース

` console.log() ` ← 前後にスペースがあると正しく動作しない場合がある

正しくは：

`console.log()` ← スペースなし

実践的な活用例

技術ブログでの使用例

# Node.js の Express でWebサーバーを作ろう

## 1. プロジェクトの初期化

まず、新しいディレクトリを作成してプロジェクトを初期化します：

```bash
mkdir my-express-app
cd my-express-app
npm init -y
```

## 2. Express のインストール

```bash
npm install express
```

## 3. アプリケーションの作成

`app.js` ファイルを作成します：

```javascript:app.js
const express = require('express');
const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(PORT, () => {
    console.log(`Server is running on port ${PORT}`);
});
```

## 4. アプリケーションの実行

```bash
node app.js
```

ブラウザで `http://localhost:3000` にアクセスすると、"Hello World!" が表示されます。

README ファイルでの使用例

# プロジェクト名

プロジェクトの説明をここに書きます。

## インストール方法

```bash
git clone https://github.com/username/project.git
cd project
npm install
```

## 使用方法

### 基本的な使い方

```javascript
const myLibrary = require('./lib');

// 基本的な関数の呼び出し
const result = myLibrary.process('input data');
console.log(result);
```

### 設定ファイル

`config.json` を作成してください：

```json
{
  "api_key": "your-api-key-here",
  "debug": true,
  "timeout": 5000
}
```

## API リファレンス

### `process(data)`

データを処理します。

**パラメータ**:
- `data` (string): 処理するデータ

**戻り値**:
- (object): 処理結果

**例**:

```javascript
const result = myLibrary.process('sample data');
// => { status: 'success', data: 'processed sample data' }
```

まとめ

コードブロックの基本ポイント

書き方の基本

  1. 3つのバッククォートで囲む：最も一般的で推奨される方法
  2. 言語名を指定：シンタックスハイライトで見やすく
  3. インラインコード：文中の短いコード片には1つのバッククォート

効果的な使い方

  • 目的に応じた使い分け：インラインコードとコードブロック
  • 適切な言語指定：正確な言語名で色分けを有効活用
  • 説明と組み合わせ：コードの前後に分かりやすい解説

よくある間違いを避ける

  • バッククォートの数を正しく（最低3つ）
  • 言語名は小文字で正確に
  • 文字エンコーディングはUTF-8で保存

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました