Git Integration - ootomonaiso/docusaurus_edit GitHub Wiki

Git連携機能

Docusaurus EditorのGit統合機能について詳しく説明します。

Git連携の概要

Docusaurus Editor は Git と深く統合されており、ドキュメント編集からバージョン管理、公開までのワークフローを効率化します。

主な機能

  • 自動コミット: ドキュメント変更の自動追跡
  • ブランチ管理: 機能別ブランチでの編集
  • プルリクエスト: GitHub/GitLab との連携
  • 変更履歴: ファイル単位での変更追跡

基本的なGit操作

初期設定

# Git リポジトリの初期化（必要な場合）
git init

# リモートリポジトリの設定
git remote add origin https://github.com/username/repository.git

# ユーザー情報の設定
git config user.name "Your Name"
git config user.email "[email protected]"

VS Code でのGit設定

{
  "docusaurusEditor.git.autoCommit": true,
  "docusaurusEditor.git.commitMessageTemplate": "docs: update {filename}",
  "docusaurusEditor.git.pushAfterCommit": false,
  "docusaurusEditor.git.createPullRequest": true
}

自動コミット機能

有効化と設定

  1. VS Code の設定を開く（Ctrl+,）
  2. "Docusaurus Editor" で検索
  3. "Auto Commit" オプションを有効化

コミットメッセージのテンプレート

// カスタムテンプレート例
{
  "docusaurusEditor.git.commitMessageTemplate": "docs({category}): {action} {filename}\n\n{description}"
}

利用可能な変数：

  • {filename}: ファイル名
  • {category}: フォルダ名/カテゴリ
  • {action}: 操作内容（add, update, delete）
  • {description}: 自動生成された説明

自動コミットのタイミング

  • 新規ファイル作成時
  • 既存ファイルの保存時
  • ドラッグ&ドロップによる位置変更時
  • フロントマターの更新時

ブランチ管理

機能ブランチでの作業

# 新機能用ブランチの作成
git checkout -b feature/new-documentation

# 編集作業
# ... Docusaurus Editor での編集 ...

# 変更をコミット
git add .
git commit -m "docs: add new documentation section"

# リモートにプッシュ
git push origin feature/new-documentation

VS Code 統合でのブランチ操作

  1. 左下のブランチ名をクリック
  2. 新しいブランチを作成または既存ブランチに切り替え
  3. Docusaurus Editor で編集作業を継続

プルリクエスト連携

GitHub 連携

{
  "docusaurusEditor.git.github.enabled": true,
  "docusaurusEditor.git.github.token": "ghp_xxxxxxxxxxxx",
  "docusaurusEditor.git.github.repository": "username/repository"
}

自動プルリクエスト作成

  1. 機能ブランチで作業完了
  2. コマンドパレットで "Docusaurus: Create Pull Request"
  3. テンプレートに基づいてPR作成

PRテンプレート

## 変更内容
- [ ] 新規ドキュメント追加
- [ ] 既存ドキュメント更新
- [ ] 構造変更

## 確認事項
- [ ] リンクの動作確認
- [ ] 画像表示の確認
- [ ] SEO メタデータの確認

## 関連Issue
Closes #123

変更履歴の管理

ファイル単位の履歴

TreeView で各ファイルの変更状況を確認：

  • M: Modified（変更済み）
  • A: Added（新規追加）
  • D: Deleted（削除済み）
  • R: Renamed（名前変更）

詳細な差分表示

  1. TreeView でファイルを右クリック
  2. "Show Git History" を選択
  3. 変更履歴と差分を確認

コンフリクト解決

マージコンフリクトの処理

<<<<<<< HEAD
# 既存のタイトル
=======
# 新しいタイトル
>>>>>>> feature-branch

VS Code の統合マージツールを使用：

  1. コンフリクトファイルをクリック
  2. "Accept Current Change" または "Accept Incoming Change"
  3. 手動での調整も可能

フロントマターのコンフリクト

---
title: Document Title
<<<<<<< HEAD
sidebar_position: 1
=======
sidebar_position: 2
>>>>>>> feature-branch
description: Document description
---

CI/CD 連携

GitHub Actions の設定

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**' ]
  pull_request:
    branches: [ main ]
    paths: [ 'docs/**' ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install dependencies
      run: npm ci
    - name: Build documentation
      run: npm run build
    - name: Deploy to GitHub Pages
      if: github.ref == 'refs/heads/main'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./build

自動デプロイ

  1. メインブランチへのマージ時に自動ビルド
  2. GitHub Pages への自動デプロイ
  3. デプロイ状況の通知

バックアップとリストア

自動バックアップ

{
  "docusaurusEditor.backup.enabled": true,
  "docusaurusEditor.backup.interval": "1h",
  "docusaurusEditor.backup.location": ".vscode/backups"
}

手動バックアップ

# 現在の状態をタグ付け
git tag -a v1.0.0 -m "Documentation v1.0.0"
git push origin v1.0.0

# ブランチでのバックアップ
git checkout -b backup/$(date +%Y%m%d)
git push origin backup/$(date +%Y%m%d)

Git フック

プリコミットフック

#!/bin/sh
# .git/hooks/pre-commit

# Markdownファイルのリント
npx markdownlint docs/**/*.md

# 画像最適化
find docs -name "*.png" -exec optipng {} \;

# フロントマターの検証
node scripts/validate-frontmatter.js

プリプッシュフック

#!/bin/sh
# .git/hooks/pre-push

# ビルドテスト
npm run build

# リンクチェック
npm run link-check

トラブルシューティング

よくある問題

コミットができない

# ユーザー情報が未設定の場合
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# ファイルが大きすぎる場合
git config http.postBuffer 524288000

プッシュが失敗する

# 認証情報の確認
git config --list | grep credential

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

# 強制プッシュ（注意が必要）
git push --force-with-lease

ブランチが同期されない

# リモートブランチの最新化
git fetch origin

# ローカルブランチのリセット
git reset --hard origin/main

デバッグコマンド

# Git状態の確認
git status
git log --oneline -10
git branch -a

# リモート接続の確認
git remote show origin

# 設定の確認
git config --list

セキュリティ考慮事項

認証情報の管理

  • GitHub Personal Access Token の安全な保管
  • VS Code の認証情報ストアの利用
  • 環境変数での token 管理

機密情報の除外

# .gitignore
.env
.env.local
secrets/
private/
*.key
*.pem

アクセス権限

  • リポジトリの適切な権限設定
  • ブランチ保護ルールの設定
  • レビュー必須の設定

高度な機能

Git LFS (Large File Storage)

# 大きなファイルの管理
git lfs track "*.png"
git lfs track "*.jpg"
git lfs track "*.pdf"

サブモジュール

# ドキュメント用サブモジュール
git submodule add https://github.com/username/shared-docs.git docs/shared

Worktree

# 複数バージョンの並行作業
git worktree add ../docs-v2 v2-branch