よくある質問：テーブルがフォーマットされない場合

このレッスンでできること

このレッスンでは、プラグイン使用時の一般的な問題を素早く診断し、解決する方法を学びます：

• テーブルがフォーマットされない原因を見つける
• 「無効なテーブル構造」エラーの意味を理解する
• プラグインの既知の制限と適用されないシナリオを知る
• 設定が正しいかどうかを素早く検証する

---

問題1：テーブルが自動的にフォーマットされない

症状

AIがテーブルを生成したが、列幅が不揃いで整列されていない。

可能な原因と解決策

原因1：プラグインが設定されていない

確認手順：

1. .opencode/opencode.jsonc ファイルを開く
2. プラグインが plugin 配列にあるか確認する：

{
  "plugin": ["@franlol/opencode-md-table-formatter@0.0.3"]
}

3. ない場合は、プラグイン設定を追加する
4. OpenCodeを再起動して設定を有効にする

設定フォーマット

バージョン番号とパッケージ名が正しいことを確認してください。@franlol/opencode-md-table-formatter + @ + バージョン番号の形式を使用します。

原因2：OpenCodeが再起動されていない

解決策：

プラグインを追加した後、OpenCodeを完全に再起動する必要があります（ページをリロードするだけではダメです）。そうすることでプラグインが読み込まれます。

原因3：テーブルに区切り行がない

症状の例：

| Name | Age |
| Alice | 25 |
| Bob | 30 |

このようなテーブルはフォーマットされません。

解決策：

区切り行（2行目、|---| 形式）を追加します：

| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |

区切り行の役割

区切り行はMarkdownテーブルの標準構文で、ヘッダー行とコンテンツ行を区別するために使用され、配置方法を指定するためにも使用されます。プラグインは区切り行を検出しないとテーブルをフォーマットしません。

原因4：OpenCodeのバージョンが古すぎる

確認手順：

1. OpenCodeのヘルプメニューを開く
2. 現在のバージョン番号を確認する
3. バージョン >= 1.0.137 であることを確認する

解決策：

最新バージョンのOpenCodeにアップグレードしてください。

バージョン要件

プラグインは experimental.text.complete フックを使用しています。このAPIはOpenCode 1.0.137以降で利用可能です。

---

問題2：「invalid structure」コメントが表示される

症状

テーブルの末尾に以下が表示される：

<!-- table not formatted: invalid structure -->

「無効なテーブル構造」とは

プラグインは各Markdownテーブルを検証し、検証に合格したテーブルのみをフォーマットします。テーブル構造が規格に準拠していない場合、プラグインは元のテキストを保持し、このコメントを追加します。

一般的な原因

原因1：テーブルの行数が不足している

エラーの例：

| Name |

1行しかなく、フォーマットが不完全です。

正しい例：

| Name |
|---|

少なくとも2行（区切り行を含む）が必要です。

原因2：列数が一致していない

エラーの例：

| Name | Age |
|--- | ---|
| Alice |

1行目は2列、2行目は1列で、列数が一致していません。

正しい例：

| Name | Age |
|--- | ---|
| Alice | 25 |

すべての行の列数は同じである必要があります。

原因3：区切り行がない

エラーの例：

| Name | Age |
| Alice | 25 |
| Bob | 30 |

|---|---| のような区切り行がありません。

正しい例：

| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |

素早く診断する方法

以下のチェックリストを使用してください：

• [ ] テーブルが少なくとも2行ある
• [ ] すべての行の列数が同じである（各行にいくつの | があるか数えてください）
• [ ] 区切り行が存在する（通常2行目は |---| 形式）

上記をすべて満たしているのにエラーが発生する場合は、隠し文字や余分なスペースが列数の計算を間違えていないか確認してください。

---

問題3：「table formatting failed」コメントが表示される

症状

テキストの末尾に以下が表示される：

<!-- table formatting failed: {エラーメッセージ} -->

原因

プラグイン内部で予期しない例外がスローされました。

解決策

1. エラーメッセージを確認する：コメントの {エラーメッセージ} 部分に具体的な問題が記載されています
2. テーブルの内容を確認する：極端な特殊なケース（超長い1行、特殊文字の組み合わせなど）がないか確認してください
3. 元のテキストを保持する：失敗しても、プラグインは元のテキストを破壊しません。あなたのコンテンツは安全です
4. 問題を報告する：問題が繰り返し発生する場合は、GitHub Issues で問題を報告してください

エラーの分離

プラグインはtry-catchでフォーマットロジックをラップしているため、エラーが発生してもOpenCodeのワークフローは中断されません。

---

問題4：一部のテーブルタイプはサポートされていない

サポートされていないテーブルタイプ

HTMLテーブル

サポートされていません：

<table>
  <tr><th>Name</th></tr>
  <tr><td>Alice</td></tr>
</table>

サポート対象：Markdownパイプテーブル（Pipe Table）のみ

複数行のセル

サポートされていません：

| Name | Description |
|--- | ---|
| Alice | Line 1<br>Line 2 |

サポートされていない理由

プラグインはAIが生成するシンプルなテーブル用に設計されています。複数行のセルはより複雑なレイアウトロジックが必要です。

区切り行のないテーブル

サポートされていません：

| Name | Age |
| Alice | 25 |
| Bob | 30 |

区切り行が必要です（上記の「原因3」を参照）。

---

問題5：テーブルをフォーマットしても整列されない

可能な原因

原因1：非表示モードが有効になっていない

プラグインはOpenCodeの非表示モード（Concealment Mode）用に最適化されています。このモードではMarkdown記号（**、* など）が非表示になります。

エディタで非表示モードが有効になっていない場合、Markdown記号が実際の幅を占めるため、テーブルが「整列されていない」ように見えることがあります。

解決策：

OpenCodeの非表示モードが有効になっていることを確認してください（デフォルトで有効です）。

原因2：セルの内容が長すぎる

セルの内容が非常に長い場合、テーブルが非常に広く引き伸ばされることがあります。

これは正常な動作です。プラグインはコンテンツを切り詰めません。

原因3：インラインコード内の記号

インラインコード（`**code**`）内のMarkdown記号は文字通り幅として計算され、削除されません。

例：

| 記号 | 幅 |
|--- | ---|
| 普通のテキスト | 4 |
| `**bold**` | 8 |

これは正しい動作です。非表示モードではコードブロック内の記号は表示されるためです。

---

このレッスンのまとめ

このレッスンで学んだこと：

• テーブルがフォーマットされない診断：設定、再起動、バージョン要件、区切り行の確認
• 無効なテーブルエラーの理解：行数、列数、区切り行の検証
• 既知の制限の識別：HTMLテーブル、複数行セル、区切り行のないテーブルはサポートされていない
• 素早い自己チェック：チェックリストを使用してテーブル構造を検証する

---

まだ解決しない場合

上記の問題をすべて確認しても問題が解決しない場合：

1. 完全なログを確認する：プラグインはデフォルトでサイレント実行され、詳細なログはありません
2. Issueを提出する：GitHub Issues でテーブルの例とエラーメッセージを提供してください
3. 上級レッスンを参照する：テーブル仕様 と 非表示モードの仕組み を読んで、より技術的な詳細を理解してください

---

次のレッスンの予告

次のレッスンでは 既知の制限：プラグインの境界線 を学びます。

学べること：

• プラグインの設計上の境界と制約
• 将来可能な拡張機能
• あるシナリオがこのプラグインに適しているかどうかを判断する方法

---

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日時：2026-01-26

機能	ファイルパス	行番号
テーブル検証ロジック	index.ts	70-88
テーブル行検出	index.ts	58-61
区切り行検出	index.ts	63-68
エラー処理	index.ts	15-20
無効なテーブルコメント	index.ts	44-47

重要なビジネスルール：

• isValidTable()：テーブルが少なくとも2行、すべての行の列数が一致、区切り行が存在することを検証する（70-88行目）
• isSeparatorRow()：正規表現 /^\s*:?-+:?\s*$/ を使用して区切り行を検出する（63-68行目）
• 列の最小幅：3文字（115行目）

エラー処理メカニズム：

• try-catchでメイン処理関数をラップする（15-20行目）
• フォーマット失敗：元のテキストを保持 + <!-- table formatting failed: {message} --> コメントを追加
• 検証失敗：元のテキストを保持 + <!-- table not formatted: invalid structure --> コメントを追加