sandboxer-yandex-wiki-sync 0.1.2

Sync local Markdown files with Yandex Wiki

sandboxer-yandex-wiki-sync

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

CLI-инструмент для двусторонней синхронизации локальной документации (Markdown) с Yandex Wiki.

Документация: https://sandboxer-ai.github.io/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 с прогресс-барами.

📦 Установка

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

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

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

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

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

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

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.
2. Создайте приложение (Web services).
3. В правах выберите Yandex Wiki API (чтение и запись).
4. Получите токен.

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

export WIKI_SYNC_TOKEN="y0_your_oauth_token..."

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

3. Запуск

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

sb-wiki

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

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

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

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

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

Файл .wiki-sync.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.

Если вы нашли баг или хотите предложить функцию:

1. Создайте Issue.
2. Сделайте Fork репозитория.
3. Отправьте Pull Request.

📄 Лицензия

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

---

Built with ❤️ by Sandboxer AI