sandboxer-yandex-wiki-sync 0.1.3
Sync local Markdown files with Yandex Wiki
License: MIT
Requires Python: >=3.11
Keywords: cli, markdown, sandboxer, sync, wiki, yandex

# sandboxer-yandex-wiki-sync

> **Отказ от ответственности:** Эта библиотека — open-source проект **Sandboxer**, не связанный с Yandex LLC. Использование подчиняется условиям Yandex API Terms of Service.

CLI-инструмент для двусторонней синхронизации локальной документации (Markdown) с [Yandex Wiki](https://wiki.yandex.ru).

[![CI](https://github.com/Sandboxer-ai/sandboxer-yandex-wiki-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandboxer-ai/sandboxer-yandex-wiki-sync/actions/workflows/ci.yml)
[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11--3.14-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/sandboxer-yandex-wiki-sync)](https://pypi.org/project/sandboxer-yandex-wiki-sync/)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://sandboxer-ai.github.io/sandboxer-yandex-wiki-sync/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Typed](https://img.shields.io/badge/typing-typed-blue.svg)](https://peps.python.org/pep-0561/)

**Документация:** [https://sandboxer-ai.github.io/sandboxer-yandex-wiki-sync/](https://sandboxer-ai.github.io/sandboxer-yandex-wiki-sync/)

**Репозиторий:** [https://github.com/Sandboxer-ai/sandboxer-yandex-wiki-sync](https://github.com/Sandboxer-ai/sandboxer-yandex-wiki-sync)

---

## 🚀 Зачем это нужно?

Вести документацию в веб-интерфейсе Wiki неудобно: нет версионирования, Code Review, нормального поиска по файлам и любимого редактора (VS Code, JetBrains).

**sandboxer-yandex-wiki-sync** решает эту проблему, позволяя применить подход **Docs as Code**:
1. Пишите документацию в Markdown локально.
2. Храните её в Git вместе с кодом.
3. Автоматически публикуйте в Yandex Wiki через CI/CD или вручную одной командой.

## ✨ Возможности

- 🔄 **Двусторонняя синхронизация**:
    - `push`: Загрузка локальных изменений в Wiki.
    - `pull`: Скачивание правок, сделанных коллегами в веб-интерфейсе.
- 🧠 **Умное отслеживание**:
    - Синхронизация только изменённых файлов (по хешу контента).
    - Обнаружение и разрешение конфликтов (если файл изменен и там, и тут).
- 🛠 **Удобство работы**:
    - Поддержка вложенных папок (автоматическое создание структуры в Wiki).
    - Игнорирование служебных файлов (`.gitignore`-style).
    - Красивый интерактивный UI с прогресс-барами.

## 📦 Установка

```bash
# Рекомендуемый способ (изолированное окружение)
pipx install sandboxer-yandex-wiki-sync

# Или через pip
pip install sandboxer-yandex-wiki-sync

# Или через uv
uv tool install sandboxer-yandex-wiki-sync
```

## ⚡ Быстрый старт

### 1. Инициализация проекта

Перейдите в папку с вашим проектом и запустите инициализацию:

```bash
sb-wiki init
```

Вас попросят ввести:
- **Org ID**: ID вашей организации (можно найти в URL страницы Wiki: `.../wiki/org/<ID>/...`).
- **Slug**: Базовый путь в Wiki, куда будет загружаться документация (например, `users/my-user/docs` или `projects/backend`).

Будет создан файл конфигурации `.wiki-sync.toml`.

### 2. Получение токена

Для работы нужен OAuth токен с правами на чтение и запись в Wiki.

1. Перейдите на [Яндекс.OAuth](https://oauth.yandex.ru/).
2. Создайте приложение (Web services).
3. В правах выберите **Yandex Wiki API** (чтение и запись).
4. Получите токен.

Установите токен как переменную окружения (безопасный способ):

```bash
export WIKI_SYNC_TOKEN="y0_your_oauth_token..."
```

> ⚠️ **Важно:** Никогда не сохраняйте токен в `config.toml` или в коде, если вы планируете коммитить эти файлы в репозиторий!

### 3. Запуск

Запустите интерактивное меню:

```bash
sb-wiki
```

Или используйте прямые команды:

```bash
# Проверить, какие файлы изменены
sb-wiki status

# Загрузить изменения в Wiki
sb-wiki push

# Скачать правки из Wiki
sb-wiki pull
```

## ⚙️ Конфигурация

Файл `.wiki-sync.toml`:

```toml
[wiki]
org_id = "123456"                            # ID организации
base_slug = "users/dev/project-docs"         # Корневой раздел в Wiki
docs_dir = "docs"                            # Локальная папка с Markdown

[sync]
ignore = ["*.draft.md", "SECRET.md"]         # Игнорируемые файлы
strip_title = true                           # Убирать первый заголовок # при загрузке (Wiki сама добавляет заголовок)
timeout = 60                                 # Таймаут запросов (сек)
```

## 🤝 Contributing

Мы приветствуем вклад в развитие проекта! Подробное руководство см. в [CONTRIBUTING.md](CONTRIBUTING.md).

Если вы нашли баг или хотите предложить функцию:
1. Создайте [Issue](https://github.com/Sandboxer-ai/sandboxer-yandex-wiki-sync/issues).
2. Сделайте Fork репозитория.
3. Отправьте Pull Request.

## 📄 Лицензия

Проект распространяется под лицензией MIT. Подробнее см. файл [LICENSE](LICENSE).

---

<p align="center">
  Built with ❤️ by <strong>Sandboxer AI</strong>
</p>