# Hatena Blog Markdown

> はてなブログのMarkdownモードで記事を書く際の記法ルールとベストプラクティス。本文の見出しはh2から始め、はてな独自の記法（目次、フォトライフ、TeX数式など）を正しく使用する。

- Skill: `redamoon/hatena-blog-markdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redamoon/hatena-blog-markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redamoon/hatena-blog-markdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: redamoon (https://skillmd.com/u/redamoon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redamoon/hatena-blog-markdown

---


# はてなブログ Markdown 記法スキル

## When to Use

- はてなブログ（Markdownモード）の記事を執筆・編集する際
- はてなブログ向け記事の見出し・目次・独自記法を整える際
- はてなブログのMarkdown記法に合っているか確認・修正するとき

## Instructions

### 編集モードの確認

- はてなブログには「見たままモード」「はてな記法モード」「Markdownモード」「HTMLモード（有料プランのみ）」があります
- Markdown記法を使用する場合は **Markdownモード** を選択してください
- 一度選んだ編集モードは、途中で変更すると内容が失われる可能性があるため、投稿前に必ず確認してください

### 見出しのルール（重要）

#### 推奨される見出しレベル

はてなブログでは、記事タイトルがh1として扱われるため、本文中の見出しは以下のレベルを使用してください：

- **`##`（h2）**: セクションの大きな区切り（大見出し）
- **`###`（h3）**: セクション内の中程度の区分（中見出し）
- **`####`（h4）**: 細かな項目、補足など（小見出し）

#### 見出しの使用ルール

1. **h1（`#`）は使用しない**: 記事タイトルがh1として扱われるため、本文ではh2から始める
2. **h6（`######`）は避ける**: CSSでの表示調整が必要になる可能性があるため、一般的には使用しない
3. **階層構造を守る**: h2 → h3 → h4 の順番を守り、h2の後にh4を直接使うなど、階層を飛ばさない
4. **目次生成**: `[:contents]` を記事冒頭に入れると、h2～h4の見出しから自動的に目次が生成される

#### 見出しの例

```markdown
## セクション1（大見出し）

### サブセクション1.1（中見出し）

#### 詳細1.1.1（小見出し）
```

### 基本的なMarkdown記法

#### 段落と改行

- **段落**: 空行で区切る（`<p>`タグで囲まれる）
- **改行**: 行末に半角空白を2つ＋改行 または `<br/>` タグを使用

```markdown
これは段落1です。

これは段落2です。  
これは同じ段落内の改行です。
```

#### 強調と太字

- **イタリック**: `*強調*` または `_強調_`
- **太字**: `**太字**` または `__太字__`

```markdown
これは*強調*です。これは**太字**です。
```

#### リスト

- **箇条書き**: `- 項目`、`* 項目`、`+ 項目` のいずれかを使用
- **番号付きリスト**: `1. 項目`
- **入れ子**: 空白でインデントして表現

```markdown
- 項目1
- 項目2
  - サブ項目2.1
  - サブ項目2.2
- 項目3

1. 番号付き項目1
2. 番号付き項目2
```

#### コードブロック

- **インラインコード**: `` `コード` ``
- **コードブロック**: バッククォート3つで囲む、または行頭4スペース

```markdown
これは `インラインコード` です。

```python
def hello():
    print("Hello, World!")
```
```

#### テーブル

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| データ1 | データ2 | データ3 |
| データ4 | データ5 | データ6 |
```

#### 引用

```markdown
> これは引用文です。
> 
> 複数行の引用も可能です。
```

#### 水平線

```markdown
---
***
___
```

### はてなブログ独自の記法

#### 目次記法

記事冒頭に `[:contents]` を記述すると、h2～h4の見出しから自動的に目次が生成されます。

```markdown
[:contents]

## セクション1
...
```

#### 自動リンク記法

- URLは自動的にリンクになります: `http://example.com`
- ブログカード表示: `[http://example.com:タイトル]`

```markdown
https://example.com

[http://example.com:サンプルサイト]
```

#### Wikipedia/Google検索リンク

```markdown
[wikipedia:キーワード]
[google:検索キーワード]
```

#### 見出しへの内部リンク

見出しには自動的にid属性が付与されるため、以下のようにリンクできます：

```markdown
[このリンク](#見出し名)
```

#### フォトライフ記法（画像挿入）

```markdown
[f:id:はてなID:画像番号:オプション]
```

例：
```markdown
[f:id:hatenablog:20170217161727j:plain]
[f:id:hatenablog:20170217161727j:plain:title=パンダ:alt=アドベンチャーワールドで見たパンダ]
```

オプション：
- `plain`: 通常の画像表示
- `title=タイトル`: ツールチップ表示
- `alt=代替テキスト`: 画像が表示できないときの代替テキスト

#### TeX数式記法

```markdown
[tex: 数式]
```

インライン: `[tex: E = mc^2]`

ブロック:
```markdown
[tex: 
E = mc^2
]
```

**注意**: Markdownの中でアンダースコア `_` やキャレット `^` などを使う場合は、エスケープ（`\_`、`\^`）が必要です。

### 注意事項とベストプラクティス

#### 1. 見出しの階層構造

- h2 → h3 → h4 の順番を守る
- 階層を飛ばさない（h2の後にh4を直接使わない）
- h1、h5、h6は使用しない

#### 2. 記号のエスケープ

- 数式やコード内でMarkdownの記号（`_`、`^`、`*`など）を使う場合は、エスケープが必要
- 例: `\_`、`\^`、`\*`

#### 3. 改行と段落

- 段落ごとに空行を入れる
- 同じ段落内で改行する場合は、行末に半角空白2つ＋改行 または `<br/>` を使用

#### 4. 画像のアクセシビリティ

- フォトライフ記法を使用する際は、`alt=` オプションで代替テキストを必ず設定する
- SEOとアクセシビリティの観点から重要

#### 5. 目次の配置

- `[:contents]` は記事の冒頭（最初の見出しの前）に配置する
- 目次はh3～h5の見出しから自動生成される

#### 6. リンクの使い方

- 外部リンクは自動リンク記法を使用
- 見出しへの内部リンクは `[テキスト](#見出し名)` の形式を使用

### チェックリスト

記事を投稿する前に、以下を確認してください：

- [ ] 見出しはh2（`##`）から始まっているか
- [ ] 見出しの階層構造が正しいか（h2 → h3 → h4の順）
- [ ] h1、h5、h6を使用していないか
- [ ] 目次記法 `[:contents]` が記事冒頭にあるか（必要に応じて）
- [ ] 画像に `alt=` オプションが設定されているか
- [ ] 数式内の記号が適切にエスケープされているか
- [ ] 段落ごとに空行が入っているか
- [ ] コードブロックの言語指定が適切か

### テンプレート例

次のテンプレートは記法の並びを確認するためのサンプルであり、記事構成の推奨ではありません。記事の構成と見出しの付け方は `japanese-prose-revision` の「見出しの付け方」と `cognitive-rhythm-writing` に従ってください。

```markdown
[:contents]

## セクション1（大見出し）

本文の段落です。段落は空行で区切ります。

### サブセクション1.1（中見出し）

本文の段落です。

#### 詳細1.1.1（小見出し）

本文の段落です。

## セクション2（大見出し）

本文の段落です。
```