Перейти к основному содержимому

Прямая работа с Git для документации Docusaurus

1. Начальная настройка​

Настройка SSH для подключения к Debian серверу​

  1. Генерация SSH ключа в Windows:
ssh-keygen -t ed25519 -C "your.email@example.com"
  1. Копирование публичного ключа на сервер:
# Скопируйте содержимое файла
type C:\Users\YourUsername\.ssh\id_ed25519.pub

# На Debian сервере добавьте ключ
echo "ваш-публичный-ключ" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Настройка Git в Windows​

# Базовая конфигурация
git config --global user.name "Ваше Имя"
git config --global user.email "your.email@example.com"

# Настройка окончаний строк
git config --global core.autocrlf input

# Настройка редактора (если используете VSCode)
git config --global core.editor "code --wait"

2. Клонирование и структура проекта​

Клонирование репозитория​

# Клонирование через SSH
git clone ssh://user@debian-server:/path/to/docusaurus-repo
cd docusaurus-repo

# Проверка удаленного репозитория
git remote -v

Структура проекта документации​

docusaurus-repo/
├── docs/
│   ├── intro.md
│   ├── section1/
│   │   ├── page1.md
│   │   └── page2.md
│   └── section2/
│       └── page3.md
├── static/
│   └── img/
│       └── screenshots/
└── sidebars.js

3. Рабочий процесс​

Создание новой документации​

  1. Обновление локального репозитория:
git fetch origin
git checkout main
git pull origin main
  1. Создание новой ветки:
# Формат: docs/название-раздела
git checkout -b docs/user-guide
  1. Создание и редактирование файлов:
# Создание нового файла документации
mkdir -p docs/user-guide
code docs/user-guide/installation.md
  1. Проверка статуса и изменений:
# Просмотр измененных файлов
git status

# Просмотр изменений
git diff

# Добавление файлов
git add docs/user-guide/installation.md
  1. Создание коммита:
# Коммит изменений
git commit -m "Исправление косяков с дублированием в разделе markdown"

# Для длинного сообщения коммита
git commit
  1. Отправка изменений:
git push -u origin master
  1. Получение изменений:
git pull origin master

Порядок действий после получения изменений

# Удаляем папки с кэшем и сборкой
rm -rf node_modules/.cache
rm -rf build

# Пересобираем проект
npm run build

# Перезапускаем с обновлением окружения
pm2 restart docusaurus --update-env

Обновление существующей документации​

  1. Переключение на нужную ветку:
git checkout docs/user-guide
  1. Внесение изменений и коммит:
# После внесения изменений
git add .
git commit -m "Update installation instructions"
git push origin docs/user-guide

4. Лучшие практики​

Организация коммитов​

  1. Делайте атомарные коммиты:
# Плохо
git commit -m "Update everything"

# Хорошо
git commit -m "Update installation requirements section"
  1. Используйте понятные сообщения коммитов:
# Формат
git commit -m "тип: краткое описание

Подробное описание изменений
"

# Пример
git commit -m "docs: add API authentication guide

- Add initial authentication setup
- Include code examples
- Add troubleshooting section"

Работа с изображениями​

  1. Оптимизация изображений перед добавлением:
# Создание директории для изображений
mkdir -p static/img/user-guide
  1. Правильные пути в markdown:
![Описание изображения](/img/user-guide/screenshot.png)

5. Решение проблем​

Откат изменений​

# Отмена последнего коммита (сохранить изменения)
git reset --soft HEAD~1

# Отмена изменений в файле
git checkout -- docs/user-guide/installation.md

# Полный сброс ветки
git reset --hard origin/docs/user-guide

Конфликты слияния​

# Обновление основной ветки
git checkout main
git pull origin main

# Перебазирование вашей ветки
git checkout docs/user-guide
git rebase main

# Решение конфликтов
git add .
git rebase --continue