docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil）

[kiki830621]

Problem

Original observation（StatisticaLearning 123 報價單 PDF 實測 · 2026-04-18）:
「macdoc textutil 會把自訂 CSS 洗掉，不適合做視覺化報價；Chrome headless 才能保留排版。但加上正確的 page-break rule 就能解決換頁問題。」
— Source: AI 助手對話中的錯誤結論，基於 skill 文件的不完整描述。

這是錯誤推論。實測發現 macdoc 早已支援 HTML→PDF via playwright/Chromium（#69 實作），CSS 完整保留，@page / page-break-* / grid 全部正常。問題在 skill.md 只列了 | pdf | 轉 PDF | MD→PDF（透過 textutil）|，沒提到 HTML→PDF 路徑，導致使用者和 AI 助手以為 PDF 全走 textutil，繞過 macdoc 去用 chrome --headless 或 wkhtmltopdf。

Type

docs

Expected

~/.claude/plugins/cache/psychquant-claude-plugins/macdoc/1.1.0/skills/macdoc/skill.md 的 convert 支援格式表應明列兩條 pdf 路徑：

--to	來源	說明	Backend
pdf	MD	純文字 → PDF	textutil
pdf	HTML	HTML（含 CSS）→ PDF，保留排版	playwright Chromium

常用工作流章節也應新增範例：

# HTML（含完整 CSS / @page / page-break）→ PDF
macdoc convert --to pdf styled-quote.html --output quote.pdf

以及前置需求：

• pip install playwright && playwright install chromium

Actual

skill.md 現況（v1.1.0）：

| pdf | 轉 PDF | MD→PDF（透過 textutil）|

完全沒提 HTML→PDF。使用者看到這行會合理推論 HTML→PDF 不支援或會走 textutil 洗掉 CSS。

Impact

實務上讓我誤以為需要自己跑：

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --headless=new --disable-gpu --no-pdf-header-footer \
  --print-to-pdf=out.pdf file:///path/to/input.html

最後才發現 macdoc 一行就搞定：

macdoc convert --to pdf input.html --output out.pdf

兩者產出的 PDF 肉眼無差別（都走 Chromium），但 macdoc 版本少寫 200+ 字的指令、不用記 Chrome 路徑、不用處理 CSP/flag。

這對 AI agent 使用 macdoc skill 時尤其關鍵——AI 看文件做判斷，doc 不完整就會繞路。

Reference

• feat: 支援 HTML → PDF 轉換 (macdoc convert --to pdf) #69 feat: 支援 HTML → PDF 轉換 (macdoc convert --to pdf) — 實作此功能的 issue
• 實測檔案：一份有 STIX Two Text / Noto Serif TC / Archivo / JetBrains Mono + OKLCH + grid + @page A4 + break-before: page 的 4 頁報價單 HTML，macdoc 輸出 CSS/分頁完全正確

Proposed fix

改 skills/macdoc/skill.md 的兩個地方：

1. 第一個表格「支援格式」區塊：PDF 列補上 HTML 來源 + playwright backend 說明
2. 「常用工作流」區塊：新增「HTML → 保留排版 PDF」範例
3. 前置需求章節：列 playwright install chromium

Current Status

Phase: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

---

Current Status

Phase: implemented
Last updated: 2026-05-02 by idd-implement

Key Decisions

• macdoc skill docs now explicitly list HTML/HTM→PDF as a playwright Chromium route, separate from MD→PDF via textutil.
• Both Claude and Codex plugin source repos were updated so agents using either skill surface see the same guidance.

Scope Changes

• Included macdoc plugin metadata bump to 1.1.1 in both plugin repos; Claude marketplace metadata was updated too.

Blocking

• Awaiting PR review/merge in both plugin repos.

Commits

• fe5f7b6 docs: document macdoc HTML to PDF route (PsychQuant/psychquant-claude-plugins)
• 5e3e7c0 docs: document macdoc HTML to PDF route (PsychQuant/psychquant-codex-plugins)

PRs

• Document macdoc HTML to PDF route psychquant-claude-plugins#31
• Document macdoc HTML to PDF route psychquant-codex-plugins#1

[kiki830621]

Diagnosis

Type

docs

Root Cause / Analysis

Verified against /Users/che/Developer/psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md (plugin v1.1.0):

• Line 41: | pdf | 轉 PDF | MD→PDF（透過 textutil）| ← misleading, only lists textutil path

Verified against /Users/che/Developer/macdoc/Sources/MacDocCLI/MacDoc+Convert.swift:

• Line 29: --to accepts pdf as a target
• Line 75: case ("html", "pdf"), ("htm", "pdf"): — HTML→PDF route exists
• Line 222: guard isCommandAvailable("playwright") — backend is playwright/Chromium, preserves CSS

So the HTML→PDF via playwright path (feature from #69) is shipped and working; only the skill doc is stale.

Impact

• Single file: /Users/che/Developer/psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md
• Users (and AI agents) reading SKILL.md conclude textutil is the only PDF backend, so they bypass macdoc to use chrome --headless or wkhtmltopdf manually — losing the one-line UX that already exists
• psychquant-codex-plugins/plugins/macdoc/skills/macdoc/SKILL.md (codex mirror) has the same drift — grep confirms it exists; fix in both

Strategy

• Edit psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md:
  • Line 41 area — split the pdf row into two rows: MD→PDF (textutil) and HTML→PDF (playwright), or use a single row with both backends listed
  • Add a "HTML → 保留排版 PDF" workflow example after the existing "MD → 講義 HTML" block near line 73-76
  • Add prerequisite callout pip install playwright && playwright install chromium somewhere near the existing "前置需求" section (if present) or in the workflow block
• Mirror the same edit to psychquant-codex-plugins/plugins/macdoc/skills/macdoc/SKILL.md
• Bump plugin version (.claude-plugin/plugin.json 1.1.0 → 1.1.1 or 1.2.0) and run /plugin-tools:plugin-update macdoc per common-plugins.md

Complexity

Simple — pure markdown edit in two plugin-source files, plugin version bump, marketplace sync. No code, no tests, no coordination across more than two repos.

Risks

• Minor: ensure --css options and --full flag interactions are documented alongside PDF output (does --full apply to HTML→PDF? worth verifying and documenting while hands are in the file)
• Plugin sync hygiene: if marketplace.json doesn't bump, users won't get the updated skill. Follow the dependency-aware orchestration in /plugin-tools:plugin-update

[kiki830621]

Implementation Plan

• Edit psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md to document HTML→PDF via playwright Chromium in the convert support table, prerequisites, and workflow examples.
• Edit psychquant-codex-plugins/plugins/macdoc/skills/macdoc/SKILL.md with the same user-facing guidance.
• Bump the macdoc plugin metadata from 1.1.0 to 1.1.1 in both plugin source repos; update Claude marketplace metadata where versioned.
• Validate JSON metadata, grep for the new HTML→PDF/playwright docs, and open PRs for both plugin repos.

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• Edit psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md to document HTML→PDF via playwright Chromium -> commit fe5f7b6
• Edit psychquant-codex-plugins/plugins/macdoc/skills/macdoc/SKILL.md with the same guidance -> commit 5e3e7c0
• Bump macdoc plugin metadata from 1.1.0 to 1.1.1 in both plugin source repos -> commits fe5f7b6, 5e3e7c0
• Validate JSON metadata, grep docs, and open PRs for both plugin repos -> PRs below

Changes

• fe5f7b6 in PsychQuant/psychquant-claude-plugins: documents HTML/HTM→PDF as playwright Chromium, adds prerequisites/workflow, bumps marketplace metadata to 1.1.1.
• 5e3e7c0 in PsychQuant/psychquant-codex-plugins: mirrors the skill doc update and bumps Codex plugin metadata to 1.1.1.

PRs

• Document macdoc HTML to PDF route psychquant-claude-plugins#31
• Document macdoc HTML to PDF route psychquant-codex-plugins#1

Verification

• jq empty on edited plugin metadata JSON files.
• rg "HTML→PDF|playwright Chromium|playwright install chromium" over edited skill/plugin metadata.
• git diff --check in both plugin repos.

Scope Compliance

Only macdoc skill documentation and macdoc plugin metadata were changed. No macdoc CLI behavior was changed.

Next: verification pending