У 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, щоб відчути швидке, безпечне сканування документів у вашому браузері.