# Markdown Formatter

> Markdownファイルのフォーマットと整形を実行します。見出し構造の修正、コードブロックの整形、リンク検証、表の整列、一貫性のあるスタイル適用を行います。Markdown整形、フォーマット、スタイル統一について言及する場合に使用します。 Use when this capability is needed.

- Skill: `tomevault-io/markdown-formatter-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/markdown-formatter-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/markdown-formatter-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/markdown-formatter-3

---


# Markdown Formatter

このSkillは、Markdownファイルを美しく、読みやすく、一貫性のある形式に整形します。

## Instructions

### ステップ1: ファイル読み込みと分析

1. Readツールでファイルを読み込む
2. 現在の構造を分析：
   - 見出しレベルの一貫性
   - コードブロックの言語指定
   - リストのインデント
   - 表の整列
   - リンクの形式

### ステップ2: 見出し構造の最適化

**修正前**:
```markdown
# タイトル
### サブセクション（H3が直接H1の下にある）
## メインセクション
#### さらにサブ（階層が飛んでいる）
```

**修正後**:
```markdown
# タイトル
## メインセクション
### サブセクション
#### さらにサブ
```

**ルール**:
- H1は1つだけ（ドキュメントタイトル）
- 見出しレベルを飛ばさない（H2 → H4はNG）
- 見出しの前後に1行の空行を入れる

### ステップ3: コードブロックの整形

**修正前**:
```markdown
```
function hello() {
  console.log("Hello");
}
```
```

**修正後**:
````markdown
```javascript
function hello() {
  console.log("Hello");
}
```
````

**ルール**:
- コードブロックに言語指定を追加
- インデントを統一（2スペースまたは4スペース）
- コードブロックの前後に1行の空行

**対応言語**:
- `javascript`, `typescript`, `python`, `java`, `go`, `rust`
- `html`, `css`, `scss`, `json`, `yaml`, `markdown`
- `bash`, `sh`, `zsh`, `powershell`

### ステップ4: リストの整形

**修正前**:
```markdown
* アイテム1
  - サブアイテム（インデントが不統一）
* アイテム2
    * サブアイテム（インデントが深すぎる）
```

**修正後**:
```markdown
* アイテム1
  * サブアイテム（2スペース統一）
* アイテム2
  * サブアイテム
```

**ルール**:
- 順序なしリストは `*` または `-` で統一
- 順序ありリストは `1. 2. 3.` 形式
- サブリストは2スペースインデント
- リストの前後に1行の空行

### ステップ5: 表の整列

**修正前**:
```markdown
| Name | Age | City |
|---|---|---|
| Alice | 30 | Tokyo |
| Bob | 25 | Osaka |
```

**修正後**:
```markdown
| Name  | Age | City  |
|-------|-----|-------|
| Alice | 30  | Tokyo |
| Bob   | 25  | Osaka |
```

**ルール**:
- 列を視覚的に整列
- ヘッダー区切り線を統一（3つ以上のハイフン）
- セル内の余分なスペースを削除

### ステップ6: リンクの整形

**インラインリンク**:
```markdown
[リンクテキスト](https://example.com)
```

**参照リンク**（長いURLの場合）:
```markdown
詳細は[公式ドキュメント][1]を参照してください。

[1]: https://very-long-url-that-would-break-readability.com/path/to/resource
```

**ルール**:
- リンクテキストは明確に
- URLが長い場合は参照リンクを使用
- 相対パスと絶対パスを統一

### ステップ7: 画像の整形

**基本形式**:
```markdown
![代替テキスト](画像パス)
```

**キャプション付き**:
```markdown
![AIエージェントアーキテクチャ図](./images/architecture.png)
*図1: マルチエージェントシステムの構成*
```

**ルール**:
- alt属性（代替テキスト）を必ず記載
- 画像の前後に1行の空行
- キャプションはイタリック体

### ステップ8: 引用ブロックの整形

**修正前**:
```markdown
>引用テキスト
>複数行
```

**修正後**:
```markdown
> 引用テキスト
> 複数行
```

**ルール**:
- `>` の後にスペースを1つ
- 引用ブロックの前後に1行の空行

### ステップ9: 水平線の統一

以下のいずれかに統一：
```markdown
---
```

または

```markdown
***
```

**ルール**:
- プロジェクト全体で統一
- 水平線の前後に1行の空行

### ステップ10: 最終チェック

- [ ] 行末の余分なスペースを削除
- [ ] 連続する空行を1行にまとめる
- [ ] ファイル末尾に改行を1つ追加
- [ ] 全角・半角の統一確認

## Formatting Rules Summary

```markdown
# ✅ 正しいフォーマット

# H1タイトル

## H2メインセクション

ここに本文。段落の前後には空行を入れる。

### H3サブセクション

* リスト項目1
  * サブ項目（2スペースインデント）
* リスト項目2

```javascript
const code = "言語指定あり";
```

| 列1 | 列2 |
|-----|-----|
| A   | B   |

![画像](path.png)

> 引用テキスト

---

次のセクション...
```

## Best Practices

### スタイルガイドの一貫性

プロジェクト全体で以下を統一：

1. **見出しスタイル**: ATXスタイル（`# 見出し`）を推奨
2. **リストマーカー**: `*` または `-` のどちらかに統一
3. **コードブロック**: 必ず言語指定
4. **インデント**: 2スペースまたは4スペースに統一
5. **改行**: UNIX形式（LF）を推奨

### 日本語と英語の混在ルール

```markdown
【推奨】
日本語と English の間にはスペースを入れる。
数字の 100 個も同様。

【非推奨】
日本語とEnglishの間にスペースなし。
```

### リンクの管理

```markdown
<!-- 記事内リンク -->
[セクション1へ](#section-1)

<!-- 外部リンク -->
[公式サイト](https://example.com)

<!-- 参照リンク（長いURLの場合） -->
詳細は[こちら][ref1]を参照。

[ref1]: https://very-long-url.com/...
```

## Examples

### 使用例1: ブログ記事の整形

```
User: "このMarkdownファイルを整形してください"

Skill実行:
1. ファイル読み込み（Read）
2. 見出し構造分析
3. コードブロックに言語指定追加
4. リストのインデント統一
5. 表の整列
6. 整形済みファイルを保存（Edit）
```

### 使用例2: README.mdの一括整形

```
User: "プロジェクト内の全てのMarkdownファイルを統一フォーマットにしてください"

Skill実行:
1. Markdownファイルを検索（*.md）
2. 各ファイルを順次整形
3. スタイルガイドに従って統一
4. 整形レポート作成
```

## Linter Integration

markdownlintなどのツールと連携可能：

```bash
# markdownlintのインストール
npm install -g markdownlint-cli

# 整形前の検証
markdownlint *.md

# 自動修正
markdownlint --fix *.md
```

## Configuration Example

`.markdownlint.json` の推奨設定：

```json
{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["img", "details", "summary"]
  },
  "MD041": false
}
```

## Formatting Checklist

整形完了前に確認：

- [ ] H1が1つだけ
- [ ] 見出しレベルが階層的
- [ ] コードブロックに言語指定
- [ ] リストのインデント統一（2スペース）
- [ ] 表が整列
- [ ] 画像にalt属性
- [ ] リンクが有効
- [ ] 行末の余分なスペース削除
- [ ] ファイル末尾に改行

## Version History

- v1.0.0 (2025-01-26): 初期リリース

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/test141515111) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->