MCP HubMCP Hub
← Back to Skills

render-puzzle-docs

pjt222
Updated 2 days ago
8 views
17
2
17
View on GitHub
Metaworddesign

About

This skill renders the jigsawR Quarto documentation site for GitHub Pages, supporting full fresh/cached builds or single-page renders. It's used after content changes, during iterative editing, or when preparing documentation for releases. The skill can utilize bundled scripts or direct Quarto invocation via WSL.

Quick Install

Claude Code

Recommended
Primary
npx skills add pjt222/agent-almanac -a claude-code
Plugin CommandAlternative
/plugin add https://github.com/pjt222/agent-almanac
Git CloneAlternative
git clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/render-puzzle-docs

Copy and paste this command in Claude Code to install this skill

Documentation

渲染拼圖文件

渲染 jigsawR 之 Quarto 文件站。

適用時機

  • 內容變更後建完整文件站
  • 反覆編輯時渲染單一頁面
  • 為發布或 PR 備文件
  • 除 Quarto .qmd 文件之渲染錯誤

輸入

  • 必要：渲染模式（fresh、cached 或 single）
  • 選擇性：特定 .qmd 文件路徑（單頁模式）
  • 選擇性：是否於瀏覽器開啟結果

步驟

步驟一：擇渲染模式

模式命令時長用時
Freshbash inst/scripts/render_quarto.sh~5-7 min內容已變、快取陳舊
Cachedbash inst/scripts/render_quarto.sh --cached~1-2 min小編輯、快取仍有效
Single直接 quarto.exe~30s反覆於一頁

預期： 依當前情況擇模式：內容變或快取陳舊則 fresh，小編輯則 cached，反覆於一頁則 single。

失敗時： 若不確快取是否陳舊，預設 fresh 渲染。較久但保正確輸出。

步驟二：執行渲染

Fresh 渲染（清 _freeze 與 _site，重執所有 R 代碼）：

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

Cached 渲染（用既有 _freeze 文件）：

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

單頁（直接渲染一 .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 套件已安裝

步驟三：驗輸出

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 中。

步驟四：預覽（選擇性）

於 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: 以資潔淨輸出

常見陷阱

  • 陳舊 freeze 快取：R 代碼已變則用 fresh 渲染重建 _freeze 文件
  • 缺 R 套件：Quarto .qmd 文件恐用 renv 中無之套件；先裝之
  • 找不到 pandoc：確 RSTUDIO_PANDOC 已設於 .Renviron
  • 渲染時長：Fresh 渲染需 5-7 分鐘（14 頁含 R 執行）；反覆時用 cached 模式
  • 代碼區塊標籤：所有 R 代碼區塊應有 #| label: 以資潔淨渲染

相關技能

  • generate-puzzle — 生文件中所引之拼圖輸出
  • run-puzzle-tests — 確文件中之代碼例正確
  • create-quarto-report — 通用 Quarto 文件建立

GitHub Repository

pjt222/agent-almanac
Path: i18n/wenyan-lite/skills/render-puzzle-docs
0
agentsagentskillsai-assisted-developmentclaude-codeskillsteams

Related Skills

content-collections

Meta

This skill provides a production-tested setup for Content Collections, a TypeScript-first tool that transforms Markdown/MDX files into type-safe data collections with Zod validation. Use it when building blogs, documentation sites, or content-heavy Vite + React applications to ensure type safety and automatic content validation. It covers everything from Vite plugin configuration and MDX compilation to deployment optimization and schema validation.

View skill

polymarket

Meta

This skill enables developers to build applications with the Polymarket prediction markets platform, including API integration for trading and market data. It also provides real-time data streaming via WebSocket to monitor live trades and market activity. Use it for implementing trading strategies or creating tools that process live market updates.

View skill

creating-opencode-plugins

Meta

This skill helps developers create OpenCode plugins that hook into 25+ event types like commands, files, and LSP operations. It provides the plugin structure, event API specifications, and implementation patterns for JavaScript/TypeScript modules. Use it when you need to intercept, monitor, or extend the OpenCode AI assistant's lifecycle with custom event-driven logic.

View skill

sglang

Meta

SGLang is a high-performance LLM serving framework that specializes in fast, structured generation for JSON, regex, and agentic workflows using its RadixAttention prefix caching. It delivers significantly faster inference, especially for tasks with repeated prefixes, making it ideal for complex, structured outputs and multi-turn conversations. Choose SGLang over alternatives like vLLM when you need constrained decoding or are building applications with extensive prefix sharing.

View skill