html-slideshow
一個響應式幻燈片，打包成單一、自包含且經過最小化的 .html。
以 HTML 編寫投影片；引擎（assets/base.css + base.js）加上 Bun 建構
產生最終檔案。需要 Bun。
工作流程
- 檢查執行環境 —
bun --version（若缺少請從 bun.sh 安裝；已在 1.4.0 驗證）。 - 複製模板 — 將
assets/base.html、assets/base.css和assets/base.js複製到使用者工作區中的一個投影片資料夾內（彼此相鄰）。.html可以自由重新命名（例如my-deck.html）；base.css和base.js是透過相對路徑從.html引用的，因此重新命名它們需要 更新這些引用。 - 設定標題 — 在
.html中，編輯<title>。投影片預設為深色主題； 列印時會自動切換為強制淺色調色板。 - 新增投影片 — 在
<main id="deck">中，每個投影片一個<section class="slide">：<section class="slide"> <h2>季度財報</h2> <ul><li>營收成長 24%</li></ul> </section> - 自訂 CSS/JS — 僅限連結檔案，絕對不行行內樣式。 請勿在
.html中加入<style>或<script>區塊 — 它只包含頁面骨架和投影片內容；建構過程會將連結的檔案 內嵌到最終的自包含檔案中，這能保持原始碼可編輯且引擎單一來源。兩個經許可的自訂程式碼位置：直接編輯base.css/base.js，或 — 針對與引擎隔離的投影片專用樣式/行為 — 新增<link rel="stylesheet" href="extra.css">/<script src="extra.js" defer></script>（建構過程會內嵌它們；盡可能保持base.*不修改 — 請參閱references/bundling-assets.md）。（references/slide-patterns.md中的實用作法遵循此原則。） - 使用容器單位進行尺寸設定 — 絕對不要用
px。 每個投影片都是一個 CSS 查詢 容器，因此使用cqw/cqh/cqmin和clamp()，內容會自動縮放以適應任何 螢幕。px/pt會破壞響應式設計 — 不要使用它們（外框使用svh）。這是代理最常出錯的一條規則；完整指南請見references/responsive-units.md。 直向視口已為您處理：投影片以其橫向畫布渲染並縮放以適應，因此寬表格/網格永遠不會溢出 手機螢幕（:root上的--slide-w/--slide-h，預設為16/9）。 - 建構 — 執行技能的建構腳本：
bun scripts/build.js my-deck.html（包裝了bun build --compile --target=browser --minify my-deck.html --outdir dist；可在 Bun 支援的任何作業系統上執行）→dist/my-deck.html：一個單一、經過最小化、自包含的檔案， CSS、JS 和任何引用的資產都已內嵌。 這是您要分發的檔案。 - 驗證建構後的檔案 — 在瀏覽器工具中打開（
dist/my-deck.html的file://URL）。 通過標準：控制項正常渲染；按 ArrowRight 會將計數器前進到 "2 / N" 並將location.hash設為#2； 一個約 400×800 的視口仍顯示一個完全可見的 letterbox 投影片；按O切換總覽；列印媒體模擬 產生每頁一張投影片。訊號文件記錄在references/using-the-deck.md。如果沒有可用的瀏覽器工具，請說明已跳過視覺驗證。 - 清理 — 除了建構輸出外不會建立任何內容；請保留
my-deck.html、base.css和base.js（可編輯的原始碼）與dist/my-deck.html（您要分發的檔案）並存。如果使用者只想要單一 檔案，將dist/my-deck.html移動到他們預期放置投影片的位置，並保留投影片資料夾作為其原始碼。
參考索引
按需載入 — 不需一次全部載入：
references/using-the-deck.md— 設定、投影片合約、完整導覽、 深層連結（#5打開第 5 張投影片；#some-id打開包含該 id 的投影片； 用於引用 → 來源）、建構和列印。references/slide-patterns.md— 現成的投影片實用作法 + 撰寫指引。references/responsive-units.md— 無px的流體尺寸設定指南。references/bundling-assets.md— 內嵌 SVG / data-URI 資產（建構過程也會 內嵌相對引用）。references/engine-anatomy.md— 引擎（base.html/base.css/base.js）的對應圖，供修改時參考。examples/quickstart.html— 一個已填入內容的投影片（原始碼；建構它以獲得自包含檔案）。examples/README.md— 範例投影片的兩種形式（可讀原始碼 vs 建構後的獨立檔案）以及如何在編輯後重新建構獨立檔案。
使用時機
當輸出應一次顯示一個全螢幕時：簡報、課程、示範、狀態更新或提案。不適合滾動閱讀的散文或文件。