VitePress セットアップガイド: TypeScript・サイドバー・Biome・Markdown変換

1. TypeScript設定

tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "types": ["vitepress/client"]
  },
  "include": [".vitepress/**/*.ts", ".vitepress/**/*.vue"],
  "vueCompilerOptions": {
    "vitePressExtensions": [".md"]
  }
}

ポイント

• vitepress/client が内部で vite/client を参照し .vue モジュールの型宣言を含むため、env.d.ts や shims-vue.d.ts は不要
• vueCompilerOptions.vitePressExtensions でMarkdown内のVueコードもVolarが認識
• moduleResolution: "bundler" はVite系プロジェクトの必須設定

pnpm strict mode での注意

VitePressの内部依存（vue等）が node_modules/ 直下にhoistされない。Cannot find module vue エラーが出る場合は pnpm add -D vue で明示的にインストールする。

テーマの型付け

EnhanceAppContext を使うと型展開が深すぎて Excessive stack depth comparing types (ts 2321) になる。必要な部分だけ型付けして回避する。

import type { App } from "vue";

export default {
  extends: DefaultTheme,
  enhanceApp({ app }: { app: App }) {
    // ...
  },
};

2. サイドバー構築

ネスト構造の設計

VitePressのサイドバーは collapsed フラグでツリーを制御可能。

{
  text: 'ドキュメント',
  collapsed: false,
  items: [
    {
      text: 'セクションA',
      collapsed: true,
      items: [
        { text: 'ページ1', link: '/page1' },
        { text: 'ページ2', link: '/page2' }
      ]
    }
  ]
}

設計指針

• 深すぎるネストは避ける: 3階層（ルート→カテゴリ→ページ）が可読性の限界
• collapsed デフォルト: 関連トピックは折りたたんで関心別アクセスを支援
• Notionのデータベース構造（parent category → pages）をそのままネスト構造に変換すると自然
• ページ移行後、サイドバー生成スクリプトで自動構築可能

3. lefthook + Biome 設定

lefthook.yml

pre-commit:
  commands:
    biome:
      glob: '*.{ts,js,json,jsonc,vue,css}'
      run: pnpm biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
      stage_fixed: true

stage_fixed: true で自動修正後のファイルを再stageしてくれる。

4. Markdown変換パターン（Notion → VitePress）

ブロックタイプ別変換

Notion	Markdown
Paragraph	通常段落
Heading 1-3	#, ##, ###
Bulleted List	- item
Numbered List	1. item
Code Block	```code```
Toggle	<details><summary>
Callout	> [icon] メッセージ
Quote	> 引用文

リンク変換

• Notion内部リンク → ページIDから slug にマッピングして相対パスに変換
• 外部リンク → そのまま保持
• ファイルリンク → CDN URLに変換（必要に応じて）

ビルド時検証

VitePressビルドでデッドリンクが検出される。Notionリンク残存の有無を自動検知可能。