# Doc Compare

> Визуальное сравнение markdown-документов бок о бок (side-by-side) с ПОДСВЕТКОЙ ПРАВОК. Скрипт scripts/compare_docs.py режет документы на блоки (заголовки/абзацы/списки/таблицы), через difflib находит изменённые блоки и подсвечивает: слева красным (удалено/изменено), справа зелёным (добавлено/изменено); внутри правок — пословная подсветка (зачёркнутое красным / добавленное зелёным). Кнопка «Только изменения» прячет неизменённые блоки. Поддерживает подтягивание версии из публичного GitHub-репозитория через gh (префикс gh:owner/repo@ref:path) и режим --diff (построчная таблица difflib). Триггеры: 'сравни документы', 'doc compare', 'side-by-side', 'визуально сравнить', 'diff docs', 'сравнение оферт', 'сравнить с опубликованным', 'покажи где правки', 'подсвети изменения'.

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

---


# Doc Compare

> Визуальное сравнение markdown-документов с подсветкой правок: две колонки (слева/справа) в одном окне браузера, вкладки на каждую пару, изменённые места подсвечены, кнопка «Только изменения».

## 🎯 When to use

- Нужно визуально сравнить локальный драфт с опубликованной версией (оферты `lovii_docs` vs `axiiom-ru/lovii`).
- Сразу видеть, ГДЕ были правки: изменённые блоки подсвечены, внутри — пословно.
- Свернуть всё лишнее кнопкой «Только изменения» и смотреть только затронутые места.

## 📦 Files

- `SKILL.md` — этот файл
- `scripts/compare_docs.py` — сборщик side-by-side с подсветкой правок

## 🧰 Usage

```bash
# Локальный драфт vs опубликованное в публичном репо (gh: подтягивает через gh api)
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py \
  --pair "Опубликовано|gh:axiiom-ru/lovii@main:docs/Публичная_оферта.md|Драфт|./docs/Публичная_оферта.md" \
  --pair "Опубликовано|gh:axiiom-ru/lovii@main:docs/Оферта_присоединения.md|Драфт|./docs/Оферта_присоединения.md"

# Построчная таблица difflib (альтернатива бок-о-бок)
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py \
  --diff --pair "Старая|a.md|Новая|b.md"

# Не открывать браузер, только сгенерировать файл
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py --no-open --pair "L|l.md|R|r.md" --out /tmp/cmp.html
```

Формат `--pair`: `"ЛеваяМетка|левый_файл|ПраваяМетка|правый_файл"`.
Префикс `gh:owner/repo@ref:path` у любого из файлов = подтянуть из GitHub через `gh api` (ветка `ref` необязательна, по умолчанию `main`).

## 🔬 Как читать результат

- **Без `--diff`**: две колонки. Слева = первая версия (обычно опубликованная/старая), справа = вторая (драфт/новая).
  - 🟥 красная полоса слева — блок удалён или изменён (старое слово зачёркнуто).
  - 🟩 зелёная полоса справа — блок добавлен или изменён (новое слово подсвечено).
  - Внутри изменённого блока слова подсвечены пословно.
  - Кнопка **«Только изменения»** (в шапке) прячет всё неизменённое — остаются только затронутые места.
- **С `--diff`**: классическая таблица difflib — добавленные строки зелёные, удалённые красные, изменённые жёлтые.