#markdown (2)

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

vitepress typescript biome markdown sidebar

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リンク残存の有無を自動検知可能。

Notion MCP連携ドキュメント移行のポイント 2026/3/15

notion mcp markdown api

API キーは Internal Integration で

Public Integrationだと承認必須項目が大量。Internal Integrationなら設定が少なく、素早くセットアップできる。

ページ取得フロー

ページ一覧取得
各ページのブロック子要素を再帰取得
ブロックタイプごとにMarkdown変換

トラブルシューティング

query-data-source がエラー

データベースクエリは MCPの query-data-source より REST API 直接呼び出しが堅牢：

POST /v1/databases/{id}/query

テーブルブロック変換

テーブルブロックは table_row 子要素を取得して変換が必須。単独のテーブルブロック情報では行・セル情報が不足。

Notion 固有ブロック

toggle: details + summary で実装
callout: blockquote + emoji prefix で代替
内部リンク: notion.so/xxxx → VitePress 内リンクに変換

.mcp.json 配置

プロジェクトルートの .mcp.json は認識されるが、.claude/mcp.json は認識されない可能性あり。APIキーを含むため gitignore 必須。