報告與履歷

除了簡報，同一套工具也能寫 A4 文件。一份原始檔同時產出三樣東西：可以捲動閱讀的網頁、和列印結果一致的 A4 分頁檢視，以及 PDF。

npx slidehtml paper new q3-review            # 報告
npx slidehtml paper new my-cv --resume       # 履歷
npx slidehtml paper dev q3-review            # 預覽
npx slidehtml paper check q3-review          # 型別檢查、建置、QA、PDF，最後一行是 PASS 或 FAIL
npx slidehtml paper build q3-review          # 輸出 dist/q3-review.html 和 dist/q3-review.pdf

檔案放在 src/papers/<name>/index.tsx。寫完要跑到 PASS，並逐頁看過 qa/<name>/page-NN.png。

報告

ReportDef.blocks 是由上到下的一列區塊，分頁自動完成。

區塊用途跨頁規則
Cover封面，獨占一頁不跨頁
Toc目錄，頁碼自動填寫不跨頁
H1 H2自動編號的標題不會單獨留在頁底
P內文，支援 **粗體**、`程式碼`、[^來源]、[文字](網址)在行之間分開，每邊至少兩行
List清單在項目之間分開
Stats2–4 個關鍵數字，source 必填不跨頁
Figure帶編號的圖，source 必填不跨頁
Table帶編號的表，source 必填，閱讀檢視可排序超過 12 列才跨頁，並重複表頭
Callout重點框不跨頁
SlidePage把任意投影片範本放進一張橫向頁獨占一頁
SourceList依 [^key] 首次出現的順序產生來源清單在項目之間分開
PageBreak強制換頁

圖表：DocLine、DocBars、DocStack、DocArea。文字永遠是真實字級，手機上也看得清楚。

投影片範本是為投影設計的，縮進 A4 直向一欄會小到看不清，所以報告裡的圖用上面四種，大圖表才用 SlidePage。

引用寫成 [^key]，在 sources 裡登記，文末用 <SourceList /> 列出。引用了沒登記的來源，QA 直接判 FAIL。

履歷

ResumeDef 只有資料，換 layout 和 theme 就換了樣子，內容不用動。

layout適合
classic單欄。最穩妥，投遞系統也最容易讀取
sidebar深色側欄放聯絡方式和技能
banner彩色頁首帶關鍵數字
ledger日期放在頁邊，大字級姓名，適合設計和內容職位
showcase識別證、關鍵數字趨勢、職涯軌跡和成果對比，適合產品和營運
console真實的終端機元件放在深色頁首，加指標儀表和技術熱力格，適合工程師
portfolio第二頁放真實簡報頁面的縮圖，適合設計和內容職位

這三種版式用了元件，額外的區塊類型是 track（職涯軌跡，從第一段工作經歷生成）、impact（前後對比）、heat（使用年份）、gauges（指標儀表）和 projects（專案卡片）。badge 和 terminal 寫在 ResumeDef 頂層，趨勢寫在 highlights[].trend。

每份這樣的履歷都能產生投遞版：在頁面頂部切換，或開啟時加 ?plain=1。同一份資料變成單欄文字，元件內容轉成清單，放不下的區塊自動移到第二頁。paper build 會同時輸出 dist/<name>-plain.pdf，線上投遞系統請用這個檔案。

規則：放不下就刪內容，或給區塊寫 page: 2 放到第二頁，最多兩頁，字級不會自動縮小。內容少時，段距會自動放寬。不要用技能百分比條。highlights 只寫面試時講得清楚的數字。note 用來標註範例，真實履歷不要寫。

QA 檢查什麼

文字是否超出紙張或內文區、標題是否落單、引用和圖表是否都有來源、最小字級不低於 8pt、PDF 頁數與分頁檢視一致、字型已嵌入、PDF 文字可擷取、履歷不超過兩頁、閱讀檢視在手機上不橫向捲動。

已知限制

  • 目前只有 A4 一種紙張。
  • Chrome 產生的 PDF 把這些字型嵌成 Type 3。文字可以選取和複製，列印也是向量，但個別 PDF 閱讀器在螢幕上可能略細。
  • sidebar、banner、showcase、console 和 portfolio 是多欄版式，投遞系統擷取文字的順序可能和視覺順序不同。要過自動篩選時用 classic 或投遞版。