teaching-handbooklisted

# teaching-handbook > `<SKILL_DIR>` 代表本 SKILL.md 所在資料夾。 把 `.docx` / `.md` / `.pptx` 教學講義轉成側邊欄風格的教學網頁。 ## 範圍邊界（重要） 本 skill **只負責機械轉檔**（Stage 1）：把原檔的文字、圖、結構**忠實搬到** HTML，不改寫、不美化、不重組。 **內容理解 / 改寫 / 美化（Stage 2）不在本 skill 範圍**。原因：每份簡報的領域、讀者、風格差異太大，強行寫死自動規則只會把大部分簡報搞砸。Stage 2 由使用者**在跑完轉檔後**另起對話、依當份簡報的具體需求請 Claude 處理。 未來的維護者：**不要把美化規則寫進這個 skill**——本 skill 定位是忠實機械轉檔，美化屬於下游另一層。 若使用者指名 **codelab / Codelabs 風格**，本 skill 不處理，改用 `codelab-handout`（強意見視覺設計路線）。 ## 硬規則（不可違反） 1. **必須使用原始檔**（`.docx` / `.md` / `.pptx`），不接受先轉過的 `.htm` / `.html`（否則圖片會糊）。 2. **不要改寫 `scripts/` 下的 Python 邏輯**，直接呼叫即可。 3. **輸出檔名以輸入檔名為基底**（例如 `我的講義.docx` → `我的講義.html`），不要預設 `index.html`，避免覆蓋專案主頁。 4. 若目標輸出檔已存在，先向使用者確認再覆蓋。 ## 依套件 依賴由各腳本的 inline metadata（PEP 723）宣告，`uv run` 會自動安裝，無需手動裝套件。 ## 執行 SOP ### 步驟 1：確認輸入檔 - 使用者提供 `.docx` → 走 `docx_converter.py` - 使用者提供 `.md` → 走 `md_converter.py` - 使用者提供 `.pptx` → 走 `pptx_converter.py` - 其他副檔名 → 停下來問使用者 ### 步驟 2：確認參數（都有預設值，可略） - `--title`：瀏覽器分頁標題（預設 `教學手冊`，md 預設 `Document`） - `--sidebar-title`：側邊欄標題（docx 預設 `教學手冊導航`；pptx 預設 `投影片目錄`） - `--no-notes`（僅 pptx）：不納入講者備註。**預設納入**。 - 輸出檔名：省略則自動用輸入檔名 + `.html` 使用者若沒主動提，**直接用預設值**，不要反覆追問。 ### 步驟 3：執行轉換 DOCX： ```bash uv run <SKILL_DIR>/scripts/docx_converter.py "<input.docx>" --title "<標題>" --sidebar-title "<側邊欄標題>" ``` Markdown： ```bash uv run <SKILL_DIR>/scripts/md_converter.py "<input.md>" --title "<標題>" ``` PPTX： ```bash uv run <SKILL_DIR>/scripts/pptx_converter.py "<input.pptx>" --title "<標題>" --sidebar-title "<側邊欄標題>"