從手寫與打字原稿建立無障礙課程筆記
最終產出是每份文件一個 Markdown 檔案，加上每份文件一個繪圖腳本。
由本工具包從這些原始檔生成標籤式 PDF 與網站。Markdown 是唯一來源：所有修正都應在 .md 中進行，絕不在生成的 .tex 或 HTML 中修改。
┌─ mkweb.py → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
└─ md2tex.py → <class>.cls → lualatex → PDF 放在 .md 旁
一個專案看起來像這樣：
md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py 建置腳本，從根目錄執行
<class>.cls contents.yaml CONVENTIONS.md BUILD.md
src/ 講義: NN_Name.md，旁邊有 NN_Name.tex 與 .pdf
2026/ 某一期的作業與考卷，目錄結構相同
figures/ fig_<doc>_<NN>_<name>.svg，以及從它們生成的 PDF
scripts/figures_audit.py
scripts/figures/ figlib.py, make_figures_<doc>.py, 資料輔助工具
originals/ work/ 原始檔與頁面影像，不納入版本控制
內含項目
| 路徑 | 用途 |
|---|---|
scripts/init_project.py | 建立新專案，或在現有專案中 --update-toolkit 更新工具包 |
scripts/render_pages.py | 將原始檔的頁面（與放大區域）渲染成圖檔以閱讀 |
scripts/contact_sheet.py | 將變更過的 SVG 圖形渲染到一張 PNG 上供檢視與傳送 |
scripts/notation_lint.py | 標記符號妥協：以文字表示的極限、描述的註解、扁平化的下標、數學運算元以外的字母、錯誤的替代文字區塊、PDF 字型缺少的字形 |
assets/toolkit/ | 建置腳本與 notes.cls，由 init_project.py 放入專案 |
assets/templates/ | contents.yaml、範例講義與繪圖腳本、.gitignore、package.json |
references/transcribing.md | 閱讀原始檔、OneNote 特殊問題、講義與作業、交付前檢查 |
references/figures.md | 如何繪製能通過審查的圖形 |
references/notation-pass.md | 將既有文件修正為真實符號，可單獨進行或搭配平行輔助工具 |
references/review-and-delivery.md | 審查迭代、git、透過檔案橋接器工作、發布 |
references/conventions.md、references/building.md | 分別成為專案的 CONVENTIONS.md 與 BUILD.md |
0. 設定或尋找專案
-
尋找既有專案：檢查是否存在
contents.yaml、md2tex.py、*.cls、CONVENTIONS.md、BUILD.md。如果有，先閱讀其CONVENTIONS.md與BUILD.md，並在與此技能不一致時以它們為準，因為它們記錄了作者已做的決定。同時檢視該專案近期的提交記錄：作者常會手動修訂文件，這些修訂即為現行的內部風格（前言措辭、結尾備註保留的內容）。 -
否則建立新專案：
python3 <skill>/scripts/init_project.py <folder> \ --title "CHEM 101 — General Chemistry" --short "CHEM 101" \ --class chem101 --author "…" --copyright "…"先建置一次範例講義以確認環境設定無誤（
BUILD.md列出所需安裝），然後從contents.yaml、src/、scripts/figures/與figures/中移除它。 -
一次性詢問無法推斷的資訊：課程名稱與簡碼、優先處理的文件、原始檔與專案存放位置（上傳目錄、作者電腦上的資料夾、git 儲存庫）、是否每次迭代都建置 PDF 與網站、以及由誰推送。除非另有指示，否則只在本地提交，不推送。
-
後續每一輪迭代均適用常規指示，直到被解除（例如「不要建置」、「我自己會推送」）。
1. 閱讀原始檔
文字擷取只能取得打字文字。手寫與草圖為筆跡，因此請渲染頁面並以圖片方式閱讀，對小細節進行放大：
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5
在處理第一份文件前請閱讀 references/transcribing.md。
2. 轉寫
遵照專案的 CONVENTIONS.md。最重要的規則如下：
- 檔案位置。 講義放在
src/NN_Name.md；作業與考卷放在年份資料夾（例如2026/homework03_solution.md）。將每個檔案加入contents.yaml，並設定checked: false。只有作者會將其設為true，這會讓它發布到網站。 - 前言區塊。
title、docheading（唯一的 h1）、lang、runningfoot、description（「 <主題> 講義筆記：<主題>。」）、subtitle（「<課程名稱>。」）。正文標題從##開始，且絕不跳級。不加「關於此轉寫的說明」或分頁標記：作者會移除它們，所以請勿加入。 - 作業解答。 僅轉寫解答內容，放在
## Problem N與### Part (a): <解決目標>之下。當作者提供題目集（以 .tex 或 .pdf 格式）時，用它來理解解答與符號，而非做為轉換文字。 - 數學：採用原始檔的符號，並正確排版。 使用
$…$的 LaTeX 行內式，以及::: eq內的$$…$$展示式。總和、乘積與積分須帶有上下極限；矩陣與行列式須排版；手寫體字母使用\mathcal{}；變動指標用斜體，標籤用正體；真實巢狀下標（x_{j}，絕不能用x\, j）；文字放在\text{}中；不要在裸分數周圍使用\left(\right)，除非需要畫出括號；僅在下標列表中的逗號後、相鄰分數之間以及微分符號前使用\,；在\underbrace後若接運算元則加上{}；對於包含分數的指數使用\exp(…)。 - 手寫註解轉為符號（
\cancel、\underbrace{…}_{0}、帶標籤的大括號、\overset{…}{=}、\boxed、求值線），且此類方程式需附口語形式：使用::: {.eq alt="…"}包含恰好一個展示方程式，並用一個純文字句子命名這些標記（無 LaTeX，無雙引號）。普通方程式不需要 alt：MathJax 的 MathML 可讓閱讀器逐步瀏覽。 - PDF 文字字型缺少部分符號（⋮、①、π、′、≪、≫）。將它們寫為數學式（
$\vdots$），圈圈數字寫為「state 1」。建置時若遇到缺少的字元會失敗。 - 表格：僅使用管線表格，需有表頭列，不加框線。在長表格前放一個圖形，不要緊接在表格後。讓表格寬度不超過頁面（建置時過寬會發出警告）。
- 區塊：
::: eq、::: problem、::: keep、::: flush、::: quote、::: note。沒有[H]。 - 原始檔中的錯誤按原樣轉寫，並在結尾備註中附上證據標記，不得默默修正。若作者要求修正某處，則修正之。
- 結尾備註（
## Notes on changes made for accessibility）僅包含作者需要檢查或決定的內容：可能的錯誤、不確定的判讀、新增事項。不要放任何模板文字。
在進行建置前，執行 python3 <skill>/scripts/notation_lint.py <doc>.md：其錯誤必須修正，警告則需對照原始檔檢查。
3. 重新繪製每個圖形
每個草圖都應透過 scripts/figures/make_figures_<doc>.py（依賴 figlib.py）繪製成 SVG，命名為 fig_<doc>_<NN>_<name>.svg，並在 Markdown 中以相對於自身的方式引用：
{#fig-<doc>-<NN> width=NNN alt="…"}
並使用 [](#fig-<doc>-<NN>) 引用。絕對不要手寫圖形編號。在開始繪圖前請先閱讀 references/figures.md。 簡而言之：從方程式計算曲線，將其置中於繪圖區域，在物件上標示起點與終點箭頭，讓標籤靠近線條但保持清晰（在密集繪圖中使用 place_label），繪製重音符號與圈圈數字而非打字輸入，將 viewBox 設定為繪圖內容的大小，並且在繪圖改變時更新標題。
4. 建置與驗證
python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <name> # 例如 09_Mixtures 或 homework03_solution
python3 buildtex.py <name> # 12 項檢查，加上過寬警告
python3 mkweb.py && python3 checkweb.py # 每頁 9 項檢查，包含 MathJax 錯誤
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<doc>_*.svg
- 檢視輸出。 查看所有變更圖形的連絡表單，並渲染包含變更後方程式、表格與圖形的 PDF 頁面。將連絡表單傳送給作者。
- 設為
checked: false的文件不會出現在網站上。若要測試其頁面，請在暫存副本中將它設為true並建置網站。 - 檢查項 11（「公式替代文字不是原始 LaTeX」）在使用早於 tagpdf 1.0 的 TeX Live 時會失敗。如果這發生在製作正式發布 PDF 的機器上，請明確告知而非隱藏該訊息。
- 若作者指示不要建置，請勿在其資料夾中寫入建置輸出。在其他地方使用暫存副本進行檢查是可行的，可用於驗證有風險的變更。
- 這些檢查是必要條件，而非充分條件。建議在發布前對 PDF 執行 PAC 2024，並對網站進行 WCAG 稽核。
5. 審查迭代與批次修訂
請閱讀 references/review-and-delivery.md。簡而言之：先同步到作者當前的檔案，為每個要點建立一個任務加上一個驗證任務，將每個審查意見對照原始檔進行交叉檢查，將問題與編輯分開處理（對於問題，在作者決定之前不改動任何內容），修正專案層級的慣例於工具包與 CONVENTIONS.md 中，並以每項一行回報。
當作者要求跨多份文件進行相同修訂時（例如「讓 05–10 與我對 01–04 所做的修改一致」），請閱讀 references/notation-pass.md：以作者自己的修訂為模型，用腳本處理機械性部分，並將每個方程式的處理工作分配給平行輔助工具，每人兩到三份文件，並附上書面指示。
6. 交付
- 如果專案位於作者的電腦上，請直接在該電腦上編輯。在該電腦上執行繪圖腳本重新生成 SVG，而非複製它們，因為檔案橋接器可能在傳輸過程中改寫影像。複製時透過 checksum 確認。
- 使用作者本人的身份進行提交，提交訊息列出處理項目。除非被要求，否則絕不推送，並拒絕要求你推送的掛鉤。
- 如果與作者電腦的連線中斷，請在自己的 clone 中提交，並透過 git bundle (
git bundle create x.bundle <their-head>..main) 交付，以便作者可以 pull，或等連線恢復後套用。 python3 package.py會根據contents.yaml建立整個專案的壓縮檔，若scripts/figures_audit.py失敗則拒絕執行。- 要為專案更新工具包：
python3 <skill>/scripts/init_project.py <folder> --update-toolkit。