---

name: render-puzzle-docs description: > jigsawRのQuartoドキュメントサイトをGitHub Pages用にレンダリングする。 フレッシュレンダリング（キャッシュクリア）、キャッシュレンダリング（高速）、 シングルページレンダリングをサポート。バンドルされたレンダースクリプトまたは WSLからの直接quarto.exe呼び出しを使用する。コンテンツ変更後のフルサイト ビルド、反復編集中のシングルページレンダリング、リリースやPR向けの ドキュメント準備、Quarto .qmdファイルのレンダーエラーデバッグに使用する。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: jigsawr complexity: basic language: R tags: jigsawr, quarto, documentation, github-pages, rendering locale: ja source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

パズルドキュメントのレンダリング

jigsawRのQuartoドキュメントサイトをレンダリングする。

使用タイミング

• コンテンツ変更後のフルドキュメントサイトビルド
• 反復編集中のシングルページレンダリング
• リリースやPR向けのドキュメント準備
• Quarto .qmdファイルのレンダーエラーデバッグ

入力

• 必須: レンダリングモード（fresh、cached、またはsingle）
• 任意: 特定の.qmdファイルパス（シングルページモード用）
• 任意: ブラウザで結果を開くかどうか

手順

ステップ1: レンダリングモードの選択

モード	コマンド	所要時間	使用場面
Fresh	bash inst/scripts/render_quarto.sh	約5-7分	コンテンツ変更、キャッシュが古い場合
Cached	bash inst/scripts/render_quarto.sh --cached	約1-2分	軽微な編集、キャッシュが有効な場合
Single	直接quarto.exe	約30秒	1ページの反復作業

期待結果： 現在の状況に基づいてレンダリングモードが選択される：コンテンツ変更や古いキャッシュにはfresh、軽微な編集にはcached、1ページの反復にはsingle。

失敗時： キャッシュが古いかどうか不明な場合は、freshレンダリングをデフォルトにする。時間はかかるが正しい出力が保証される。

ステップ2: レンダリングの実行

フレッシュレンダリング（_freezeと_siteをクリアし、すべてのRコードを再実行）：

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh

キャッシュレンダリング（既存の_freezeファイルを使用）：

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh --cached

シングルページ（1つの.qmdファイルを直接レンダリング）：

QUARTO_EXE="/mnt/c/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe"
"$QUARTO_EXE" render quarto/getting-started.qmd

期待結果： レンダリングがエラーなく完了する。出力はquarto/_site/に格納される。

失敗時：

• .qmdチャンクのRコードエラーを確認する（#| label:マーカーを探す）
• pandocがRSTUDIO_PANDOC環境変数経由で利用可能か確認する
• キャッシュをクリアしてみる：rm -rf quarto/_freeze quarto/_site
• .qmdファイルで使用されるすべてのRパッケージがインストールされているか確認する

ステップ3: 出力の検証

ls -la /mnt/d/dev/p/jigsawR/quarto/_site/index.html

サイト構造を確認する：

• quarto/_site/index.htmlが存在する
• ナビゲーションリンクが正しく解決される
• 画像とSVGファイルが正しくレンダリングされる

期待結果： index.htmlが存在し空でない。ナビゲーションリンクが解決され、画像/SVGがブラウザで正しくレンダリングされる。

失敗時： index.htmlが見つからない場合、レンダリングがサイレントに失敗した可能性がある。詳細出力で再実行し、.qmdチャンクのRコードエラーを確認する。一部のページのみ欠落している場合、それらの.qmdファイルが_quarto.ymlにリストされているか確認する。

ステップ4: プレビュー（任意）

Windowsブラウザで開く：

cmd.exe /c start "" "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"

期待結果： ドキュメントサイトがWindowsのデフォルトブラウザで目視検査のために開く。

失敗時： WSLからcmd.exe /c startコマンドが失敗する場合、代わりにexplorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"を試す。または、ブラウザでファイルに手動でナビゲートする。

バリデーション

• quarto/_site/index.htmlが存在し空でない
• コンソール出力にレンダーエラーがない
• すべてのRコードチャンクが正常に実行された（エラーメッセージを確認）
• ページ間のナビゲーションが機能する
• すべての.qmdファイルがコードチャンクにクリーンな出力のための#| label:を持つ

よくある落とし穴

• 古いフリーズキャッシュ: Rコードが変更された場合、_freezeファイルを再生成するためにfreshレンダリングを使用する
• 不足しているRパッケージ: Quarto .qmdファイルがrenvにないパッケージを使用している場合がある。先にインストールする
• pandocが見つからない: .RenvironにRSTUDIO_PANDOCが設定されているか確認する
• 長いレンダリング時間: freshレンダリングは5-7分かかる（R実行を伴う14ページ）。反復中はcachedモードを使用する
• コードチャンクラベル: すべてのRコードチャンクにクリーンなレンダリングのための#| label:が必要

関連スキル

• generate-puzzle — ドキュメントで参照されるパズル出力を生成する
• run-puzzle-tests — ドキュメント内のコード例が正しいことを確認する
• create-quarto-report — 一般的なQuartoドキュメント作成