Look Scanned에서는 더 나은 문서와 더 안전한 개발 관행을 제공하기 위해 인프라를 지속적으로 개선하고 있습니다. 오늘은 How-To 문서 사이트의 중요한 업그레이드에 대한 세부 정보를 공유하게 되어 기쁩니다. 커스텀 Vue + Vite 애플리케이션에서 VitePress로 마이그레이션하는 동시에 npm Trusted Publishers를 사용하여 CI/CD 보안을 강화했습니다.

📚 VitePress로 마이그레이션한 이유

우리의 How-To 문서 사이트(github.com/lookscanned/how-to)는 Look Scanned의 포괄적인 사용 가이드 역할을 합니다. 이전 Vue + Vite 설정이 잘 작동했지만, 콘텐츠 중심 문서 사이트에는 VitePress가 더 적합하다는 것을 인식했습니다.

VitePress란 무엇인가요?

VitePress는 문서를 위해 특별히 설계된 정적 사이트 생성기입니다. Vite와 Vue 3 위에 구축되어 두 가지의 장점을 결합합니다. 즉시 사용 가능한 강력한 문서 기능과 함께 매우 빠른 개발 경험을 제공합니다.

마이그레이션의 주요 이점

🎯 문서를 위한 더 나은 아키텍처

  • 파일 기반 라우팅: 각 markdown 파일이 자동으로 페이지가 되어 콘텐츠 구성이 직관적입니다
  • 내장 문서 기능: 목차, 검색, 국제화 등이 사전 구성되어 있습니다
  • 정적 사이트 생성: 사전 렌더링된 HTML은 우수한 SEO와 즉각적인 페이지 로드를 제공합니다

⚡ 개선된 개발자 경험

  • 즉각적인 핫 리로드: 개발 중 변경 사항이 즉시 나타납니다
  • Markdown 우선: 컴포넌트 스캐폴딩이 아닌 콘텐츠에 집중
  • Vue 컴포넌트 지원: 필요할 때 markdown 내에서 커스텀 Vue 컴포넌트를 사용할 수 있습니다

🔧 더 쉬운 유지 관리

  • 더 명확한 구조: 문서가 규칙을 따르므로 기여자의 인지 부하가 감소합니다
  • 더 안정적인 빌드: VitePress의 독단적인 구조는 더 재현 가능한 빌드로 이어집니다
  • 더 나은 협업: 팀원은 깊은 Vue 지식 없이도 문서에 기여할 수 있습니다

🔒 npm Trusted Publishers로 보안 강화

VitePress 마이그레이션과 함께 중요한 보안 개선 사항을 구현했습니다. OIDC 인증을 사용한 npm Trusted Publishers입니다.

기존 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/*를 사용하도록 업데이트하여 OIDC 인증에 필요한 최신 npm 버전을 확보했습니다.

📦 릴리스 타임라인

마이그레이션은 2025년 12월 19일에 세 가지 릴리스를 통해 완료되었습니다.

  • v2.0.0: Vue + Vite에서 VitePress로의 핵심 마이그레이션(주요 변경 사항)
  • v2.0.1: 적절한 Node.js 버전으로 npm Trusted Publishers를 지원하기 위한 CI 수정
  • v2.0.2: @fontsource/noto-mono를 devDependencies로 이동하여 성능 개선

🌍 지속적인 다국어 지원

중요한 참고 사항: How-To 문서는 메인 Look Scanned 애플리케이션(lookscanned.io/en/scan에서 사용 가능)에서 항상 예제 파일로 사용되어 온 다국어 PDF를 생성합니다. 이 VitePress 마이그레이션은 해당 기능을 변경하지 않으며, 단순히 문서 인프라를 유지 및 개선하기 위한 더 나은 기반을 제공합니다.

💡 사용자에게 의미하는 바

Look Scanned의 문서를 사용하는 경우:

  • 동일한 액세스, 더 나은 경험: 문서는 동일한 URL에 유지되며 로딩 및 탐색이 개선됩니다
  • 더 안정적: 정적 사이트 생성은 더 빠른 로딩과 더 나은 안정성을 의미합니다
  • 더 나은 검색 및 발견: VitePress의 내장 검색으로 답을 더 빠르게 찾을 수 있습니다
  • 지속적인 PDF 지원: 다국어 PDF 생성이 이전처럼 계속됩니다

🚀 다음은 무엇인가

인프라 업그레이드가 완료되면서 콘텐츠 개선에 집중하고 있습니다.

  • 확장된 사용 사례: 더 많은 실용적인 예제와 단계별 가이드
  • 일관성 개선: 명확성을 위해 다국어 용어 개선
  • 향상된 PDF 내보내기: 크로스 브라우저 PDF 생성 경험 개선

오늘 Look Scanned를 사용해 보세요

Look Scanned는 파일을 어디에도 업로드하지 않고 브라우저 기반의 프라이버시 우선 PDF 스캔 효과를 제공합니다. 개선된 문서로 시작하기가 그 어느 때보다 쉬워졌습니다.

👉 브라우저에서 빠르고 안전한 문서 스캔을 경험하려면 lookscanned.io를 방문하세요.