Troubleshooting - ootomonaiso/docusaurus_edit GitHub Wiki

トラブルシューティング

Docusaurus Editorで発生する可能性のある問題と解決方法について説明します。

よくある問題と解決方法

1. TreeView が表示されない

症状

サイドバーに Docusaurus Editor のアイコンが表示されない
TreeView が空白になる

考えられる原因と解決方法

原因1: Docusaurus プロジェクトが認識されていない

# 解決方法: docs フォルダの存在確認
ls -la docs/

# docs フォルダが存在しない場合は作成
mkdir docs

原因2: 拡張機能が無効になっている

VS Code の拡張機能タブを開く
"Docusaurus Editor" を検索
有効化されているか確認

原因3: ワークスペースの問題

// .vscode/settings.json
{
  "docusaurusEditor.projectPath": "./docs"
}

2. ファイルが TreeView に表示されない

症状

一部のMarkdownファイルが表示されない
新規作成したファイルが見えない

解決方法

1. ファイル拡張子の確認

# 対応拡張子: .md, .mdx
find docs -name "*.md" -o -name "*.mdx"

2. Frontmatter の構文確認

---
title: ドキュメントタイトル
sidebar_position: 1
---

3. 手動リフレッシュ

TreeView ヘッダーの更新ボタンをクリック
または Ctrl+Shift+P → "Docusaurus: Refresh TreeView"

3. ドラッグ&ドロップができない

症状

ファイルをドラッグしても移動できない
ドロップ先が反応しない

解決方法

1. ファイルの編集権限確認

# ファイル権限の確認
ls -la docs/

# 権限の修正（必要な場合）
chmod 644 docs/**/*.md

2. Git ロック状態の確認

# Git状態の確認
git status

# ロックされたファイルの解除
git checkout -- locked-file.md

3. VS Code の再起動

ファイルが使用中の場合、VS Code を再起動

4. sidebar_position が正しく更新されない

症状

ドラッグ&ドロップ後に位置が変わらない
数値が重複している

解決方法

1. Frontmatter の手動確認

---
title: タイトル
sidebar_position: 1  # 数値型であることを確認
---

2. 重複解決

# 重複している sidebar_position を検索
grep -r "sidebar_position: 1" docs/

3. 自動修正の実行

コマンドパレット → "Docusaurus: Fix Position Conflicts"

5. Git 連携の問題

症状

自動コミットが動作しない
プッシュが失敗する

解決方法

1. Git 設定の確認

# ユーザー情報の確認
git config user.name
git config user.email

# 未設定の場合
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

2. リモートリポジトリの確認

# リモート設定の確認
git remote -v

# 認証の確認
git remote show origin

3. 権限の確認

# SSH キーの確認
ssh -T [email protected]

# HTTPSの場合、Personal Access Token の確認

6. 新規ファイル作成の問題

症状

新規ファイル作成ダイアログが表示されない
テンプレートが適用されない

解決方法

1. 権限の確認

# 書き込み権限の確認
touch docs/test.md && rm docs/test.md

2. テンプレート設定の確認

{
  "docusaurusEditor.newFile.defaultTemplate": "basic",
  "docusaurusEditor.newFile.templates": {
    "basic": {
      "frontmatter": {
        "title": "{filename}",
        "sidebar_position": "{auto}"
      }
    }
  }
}

7. パフォーマンスの問題

症状

TreeView の表示が遅い
ファイル操作が重い

解決方法

1. ファイル数の確認

# ドキュメントファイル数の確認
find docs -name "*.md" -o -name "*.mdx" | wc -l

2. パフォーマンス設定の調整

{
  "docusaurusEditor.performance.maxFiles": 500,
  "docusaurusEditor.performance.enableLazyLoading": true,
  "docusaurusEditor.treeView.autoRefresh": false
}

3. 除外パターンの設定

{
  "docusaurusEditor.treeView.excludePatterns": [
    "**/node_modules/**",
    "**/.git/**",
    "**/build/**",
    "**/*.backup.*"
  ]
}

エラーメッセージと対処法

"Invalid frontmatter format"

原因: YAML Frontmatter の構文エラー

解決方法:

# ❌ 間違った例
---
title: タイトル
sidebar_position: "1"  # 文字列型
invalid syntax here
---

# ✅ 正しい例
---
title: タイトル
sidebar_position: 1    # 数値型
description: 説明文
---

"Permission denied"

原因: ファイルアクセス権限の問題

解決方法:

# Windows
icacls docs /grant Users:F /T

# macOS/Linux
chmod -R 755 docs/

"Git repository not found"

原因: Git リポジトリが初期化されていない

解決方法:

# Git リポジトリの初期化
git init

# 初回コミット
git add .
git commit -m "Initial commit"

"Template not found"

原因: 指定されたテンプレートが存在しない

解決方法:

{
  "docusaurusEditor.newFile.defaultTemplate": "basic"  // 存在するテンプレート名
}

デバッグ情報の収集

開発者ツールでのログ確認

VS Code で Ctrl+Shift+I を押して開発者ツールを開く
Console タブでエラーメッセージを確認
"Docusaurus Editor" で検索してフィルタリング

出力パネルでのログ確認

VS Code で Ctrl+Shift+U を押して出力パネルを開く
ドロップダウンから "Docusaurus Editor" を選択
ログメッセージを確認

デバッグモードの有効化

{
  "docusaurusEditor.debug.enabled": true,
  "docusaurusEditor.debug.logLevel": "verbose"
}

診断コマンド

システム情報の確認

# VS Code バージョン
code --version

# Node.js バージョン
node --version

# Git バージョン
git --version

# OS 情報
uname -a  # Linux/macOS
systeminfo  # Windows

プロジェクト状態の確認

# プロジェクト構造
tree docs/

# Git 状態
git status
git log --oneline -5

# ファイル権限
ls -la docs/

拡張機能の診断

VS Code のコマンドパレットで以下を実行：

"Docusaurus: Run Diagnostics"
"Docusaurus: Show System Info"
"Docusaurus: Validate Project Structure"

設定のリセット

拡張機能設定のリセット

// settings.json で Docusaurus Editor の設定をすべて削除
{
  // 他の設定は残す
}

キャッシュのクリア

# VS Code のキャッシュクリア
rm -rf ~/.vscode/CachedExtensions/
rm -rf ~/.vscode/logs/

# Windows の場合
rmdir /S "%APPDATA%\Code\CachedExtensions"
rmdir /S "%APPDATA%\Code\logs"

サポートとお問い合わせ

Issue の報告

GitHub リポジトリでのIssue報告時には以下を含めてください：

環境情報
- OS とバージョン
- VS Code バージョン
- 拡張機能バージョン
再現手順
- 具体的な操作手順
- 期待した動作
- 実際の動作
ログ情報
- エラーメッセージ
- 開発者ツールのログ
- 出力パネルのログ

テンプレート例

## 環境
- OS: Windows 11
- VS Code: 1.85.0
- Docusaurus Editor: 1.0.0

## 問題の説明
TreeView でファイルをドラッグ&ドロップしても位置が変更されない

## 再現手順
1. docs/intro.md を作成
2. TreeView でファイルを別の位置にドラッグ
3. sidebar_position が更新されない

## 期待した動作
sidebar_position が自動で更新される

## 実際の動作
位置が変わらず、sidebar_position も更新されない

## ログ

Error: Cannot update frontmatter...


### コミュニティサポート

- GitHub Discussions での質問
- VS Code Marketplace のレビュー
- 公式ドキュメント（このwiki）の確認

### 緊急時の回避策

1. **拡張機能の無効化**
   - 一時的に拡張機能を無効化
   - 標準のファイルエクスプローラーを使用

2. **手動での frontmatter 編集**
   - エディタで直接 sidebar_position を編集
   - Git で手動コミット

3. **代替ワークフロー**
   - VS Code の標準機能のみを使用
   - 外部ツールでの補完