В Look Scanned мы постоянно совершенствуем нашу инфраструктуру, чтобы обеспечить лучшую документацию и более безопасные методы разработки. Сегодня мы рады поделиться подробностями о значительном обновлении нашего сайта документации How-To: миграция с пользовательского приложения Vue + Vite на VitePress, одновременно улучшая нашу безопасность CI/CD с помощью npm Trusted Publishers.

📚 Почему мы мигрировали на VitePress

Наш сайт документации How-To (github.com/lookscanned/how-to) служит комплексным руководством по использованию Look Scanned. Хотя наша предыдущая настройка Vue + Vite работала хорошо, мы признали, что VitePress будет лучшим выбором для сайта документации, ориентированного на контент.

Что такое VitePress?

VitePress — это генератор статических сайтов, специально разработанный для документации. Построенный на основе Vite и Vue 3, он сочетает в себе лучшее из обоих миров: молниеносный опыт разработки с мощными функциями документации из коробки.

Ключевые преимущества миграции

🎯 Лучшая архитектура для документации

  • Маршрутизация на основе файлов: Каждый файл markdown автоматически становится страницей, делая организацию контента интуитивной
  • Встроенные функции документации: Оглавление, поиск, интернационализация и многое другое предварительно настроены
  • Генерация статических сайтов: Предварительно отрендеренный HTML обеспечивает отличное SEO и мгновенную загрузку страниц

⚡ Улучшенный опыт разработчика

  • Мгновенная горячая перезагрузка: Изменения появляются немедленно во время разработки
  • Markdown в первую очередь: Сосредоточьтесь на контенте, а не на создании компонентов
  • Поддержка компонентов Vue: При необходимости мы все еще можем использовать пользовательские компоненты Vue внутри markdown

🔧 Упрощенное обслуживание

  • Более четкая структура: Документация следует соглашениям, снижая когнитивную нагрузку для участников
  • Более стабильные сборки: Принципиальная структура VitePress приводит к более воспроизводимым сборкам
  • Лучшее сотрудничество: Члены команды могут вносить вклад в документацию без глубоких знаний Vue

🔒 Улучшенная безопасность с npm Trusted Publishers

Наряду с миграцией VitePress мы внедрили критическое улучшение безопасности: npm Trusted Publishers с использованием аутентификации OIDC.

Проблема с традиционными токенами npm

Ранее для публикации пакетов в npm требовалось хранить долгоживущий NPM_TOKEN в секретах репозитория. У этого подхода есть несколько недостатков:

  • Риск безопасности: Токены могут быть случайно раскрыты или скомпрометированы
  • Накладные расходы на управление: Токены требуют ручной ротации и обновлений
  • Проблемы аудита: Трудно отследить, кто что и когда опубликовал

Решение: Доверенная публикация на основе OIDC

npm Trusted Publishers использует OpenID Connect (OIDC) для обеспечения безопасной публикации без токенов напрямую из GitHub Actions. Вот как это работает:

  1. Нет сохраненных секретов: Вместо сохранения токенов GitHub Actions запрашивает краткосрочные учетные данные у npm
  2. Проверка личности: npm проверяет, что запрос на публикацию пришел из авторизованного репозитория GitHub
  3. Автоматическое управление учетными данными: Учетные данные автоматически выдаются и быстро истекают

Реальные преимущества

Это изменение приносит немедленные улучшения в наш рабочий процесс разработки:

  • ✅ Больше никакого управления токенами: Нет необходимости создавать, хранить или ротировать токены npm
  • ✅ Уменьшенная поверхность атаки: Краткосрочные учетные данные минимизируют риск раскрытия
  • ✅ Лучшая аудитируемость: Каждое действие публикации привязано к конкретному запуску GitHub Actions
  • ✅ Современные лучшие практики: Соответствует принципам безопасности нулевого доверия

Техническая заметка: Для поддержки npm Trusted Publishers мы обновили нашу конфигурацию CI для использования Node.js lts/*, гарантируя, что у нас есть последняя версия npm, необходимая для аутентификации OIDC.

📦 График выпусков

Миграция была завершена через три релиза 19 декабря 2025 года:

  • v2.0.0: Основная миграция с Vue + Vite на VitePress (критическое изменение)
  • v2.0.1: Исправление CI для поддержки npm Trusted Publishers с соответствующей версией Node.js
  • v2.0.2: Улучшение производительности путем перемещения @fontsource/noto-mono в devDependencies

🌍 Продолжение многоязычной поддержки

Важное примечание: наша документация How-To генерирует многоязычные PDF-файлы, которые всегда использовались в качестве примеров файлов в основном приложении Look Scanned (доступно на lookscanned.io/en/scan). Эта миграция VitePress не меняет эту функциональность — она просто обеспечивает лучшую основу для поддержки и улучшения нашей инфраструктуры документации.

💡 Что это значит для пользователей

Если вы используете документацию Look Scanned:

  • Тот же доступ, лучший опыт: Документация остается по тому же URL с улучшенной загрузкой и навигацией
  • Более надежно: Генерация статических сайтов означает более быструю загрузку и лучшую стабильность
  • Лучший поиск и обнаружение: Встроенный поиск VitePress помогает быстрее найти ответы
  • Продолжение поддержки PDF: Генерация многоязычных PDF продолжается как прежде

🚀 Что дальше

С завершением обновления инфраструктуры мы сосредоточились на улучшении контента:

  • Расширенные примеры использования: Больше практических примеров и пошаговых руководств
  • Улучшения согласованности: Уточнение многоязычной терминологии для ясности
  • Улучшенный экспорт PDF: Улучшение опыта генерации PDF в разных браузерах

Попробуйте Look Scanned сегодня

Look Scanned предоставляет браузерные эффекты сканирования PDF с приоритетом конфиденциальности без загрузки ваших файлов куда-либо. Улучшенная документация делает начало работы проще, чем когда-либо.

👉 Посетите lookscanned.io, чтобы испытать быстрое, безопасное сканирование документов в вашем браузере.