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 日に 3 つのリリースを通じて完了しました:

  • 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 にアクセスして、ブラウザで高速で安全なドキュメントスキャンを体験してください。