---
title: "Міграція документації Look Scanned How-To на VitePress з покращеною безпекою"
description: "Дізнайтеся, як Look Scanned оновив свою інфраструктуру документації, мігруючи з Vue + Vite на VitePress, одночасно впроваджуючи npm Trusted Publishers з OIDC для безпечних випусків пакетів без токенів."
date: 2025-12-19T07:55:33.000Z
lang: uk
source: https://lookscanned.io/uk/blog/migrating-look-scanned-how-to-to-vitepress
tags: ["vitepress", "документація", "безпека", "cicd", "npm"]
---

# Міграція документації Look Scanned How-To на VitePress з покращеною безпекою

У [Look Scanned](https://lookscanned.io) ми постійно вдосконалюємо нашу інфраструктуру для забезпечення кращої документації та безпечніших практик розробки. Сьогодні ми раді поділитися деталями про значне оновлення нашого сайту документації How-To: міграцію з кастомного додатка Vue + Vite на VitePress, одночасно покращуючи нашу безпеку CI/CD за допомогою npm Trusted Publishers.

## 📚 Чому ми мігрували на VitePress

Наш сайт документації How-To ([github.com/lookscanned/how-to](https://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](https://docs.npmjs.com/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](https://lookscanned.io/en/scan)). Ця міграція VitePress не змінює цю функціональність—вона просто забезпечує кращу основу для підтримки та покращення нашої інфраструктури документації.

## 💡 Що це означає для користувачів

Якщо ви використовуєте документацію Look Scanned:

- **Той самий доступ, кращий досвід**: Документація залишається на тому ж URL з покращеним завантаженням та навігацією
- **Надійніше**: Генерація статичного сайту означає швидше завантаження та кращу стабільність
- **Кращий пошук та виявлення**: Вбудований пошук VitePress допомагає швидше знаходити відповіді
- **Постійна підтримка PDF**: Генерація багатомовних PDF продовжується як і раніше

## 🚀 Що далі

З завершеним оновленням інфраструктури ми зосереджуємося на покращенні контенту:

- **Розширені випадки використання**: Більше практичних прикладів та покрокових посібників
- **Покращення узгодженості**: Уточнення багатомовної термінології для ясності
- **Покращений експорт PDF**: Покращення досвіду генерації PDF у різних браузерах

## Спробуйте Look Scanned сьогодні

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

👉 **Відвідайте [lookscanned.io](https://lookscanned.io), щоб відчути швидке, безпечне сканування документів у вашому браузері.**