codelab-handoutlisted

# codelab-handout 把上課內容（口述、docx、pdf、pptx、md）轉成 Google Codelabs 風格的單檔 HTML 講義。學生雙擊就能開，左側 sticky 目錄、每章節時間標記、明暗主題、三段字級。 > `<SKILL_DIR>` 代表本 `SKILL.md` 所在的資料夾。腳本路徑為 `<SKILL_DIR>/scripts/build.py`、範本為 `<SKILL_DIR>/assets/template.html`。 ## 範圍邊界 本 skill 只產 Codelabs 風格的強意見視覺設計；要忠實保留原檔樣式（Word 顏色、原圖）請用 `teaching-handbook`。 **不要這樣修**： - ~~拿掉 build.py 的 skill 資料夾輸出守門~~ — repo 會被產出物弄髒 - ~~在 build.py 裡寫死內容改寫規則~~ — 內容語感是步驟 2 LLM 的工作（腳本苦力 / LLM 判斷分工） ## 步驟 1：依輸入類型準備 markdown | 輸入 | 處理方式 | |------|---------| | 口述大綱／主題 | 直接寫 markdown（格式見步驟 2）| | 現有 markdown | 跳過寫作，直接到步驟 3 | | docx / pdf | 先轉成 markdown 再整理結構：用 markitdown CLI（`pip install "markitdown[all]"`）或已安裝的 markitdown skill；沒有 markitdown 時，docx 可退 pandoc／mammoth、pdf 退 pymupdf | | pptx | 同上（markitdown CLI 或 skill）；沒有時退 python-pptx 解析，再轉 markdown | ## 步驟 2：撰寫 markdown **語感**：講義要口語化，像老師上課的口氣（用比喻、「我們來……」、blockquote 標小提醒、適度幽默但不裝年輕）。不確定語感時讀 `<SKILL_DIR>/references/example_input.md`。 **格式規範**： ````markdown --- title: 講義標題 duration: 60 # 選填，總分鐘數 authors: 講師名字 # 選填 --- ## 章節一：標題 Duration: 5 內容文字。每個 `##` 會變成一個獨立區塊與目錄項。 ```python print("程式碼區塊會自動加複製按鈕") ``` > 💡 引言會渲染成有底色的提示框 ```` **章節設計原則**： - 每個 `##` 是一個完整步驟，學員看完一個 `##` 應該可以喘口氣 - 5–8 個章節最理想（多了側邊欄擁擠） - `Duration` 用整數分鐘 - 首章節寫「今天要做什麼」、尾章節寫「你帶走了什麼」 ## 步驟 3：執行 build.py > ⚠️ **成品不能輸出到 skill 資料夾**。`scripts/build.py` 會主動擋下。輸入也不要放在 skill 資料夾，建議輸入跟輸出都放在使用者專案目錄或 `~/Documents/`。 ```bash python3 <SKILL_DIR>/scripts/build.py 輸入路徑/講義.md -o 輸出路徑/講義.html ``` （Windows 用 `python` 取代