HTML 說明頁面
使用者在瀏覽器中閱讀這些頁面,並透過 Cmd+點擊直接從頁面跳到 VS Code。他們能從泳道圖中理解流程,這比閱讀段落文字快得多,而且他們希望每個頁面只回答他們問的問題,不多也不少。
此技能中的檔案
assets/template.html:每個頁面的起點。複製它,永遠不要從頭開始寫頁面。references/DESIGN.md:每個頁面都遵循的設計,始終以深色形式呈現,每個連結都是藍色藥丸(references/page.md,「外觀」)。當頁面需要一個顏色或模板中沒有的元素時請閱讀它。references/page.md:檔案名稱和位置、側邊欄、檔案連結、任務區塊、連結頁面區塊、主頁面與說明頁面。建立頁面或變更其結構時請閱讀它。references/writing.md:問題區塊和任何散文。在撰寫文字前請閱讀它。references/diagrams.md:泳道圖的外觀及其檢查方式。在繪製或編輯任何圖表前請閱讀它。references/playable.md、assets/player.js、assets/player.css:可播放的泳道圖。當使用者說「可播放」,或編輯含有div.player的頁面時請閱讀它們。
外觀
每個頁面都遵循 references/DESIGN.md,始終保持深色,每個連結都是藍色藥丸以突顯其可點擊性:底線表示檔案,↗ 表示另一個頁面,兩者都沒有表示同一個頁面的章節(references/page.md,「外觀:DESIGN.md,始終深色」和「三種連結」)。模板已經做到這一點。每個圖表都位於一個可調整大小、縮放和拖動的面板中(references/diagrams.md,「圖表區塊」)。
保持頁面簡潔
一個頁面只包含使用者要求的內容。每一個額外的區塊、表格或註解都是他們必須閱讀過去才能找到答案的內容。
- 區塊: 只包含請求所需的部分。一個泳道圖加上周圍的簡短段落就是一個區塊。永遠不要添加使用者未要求的區塊:沒有摘要、沒有清單、沒有「原因」區塊、沒有過往決策的記錄。
- 表格: 僅在使用者要求時才使用。改為撰寫段落和泳道圖。
- 圖表下方: 什麼都不要放。沒有檔案列表、沒有註解、沒有「未繪製」的行。如果需要一句話來理解圖表,請將它放在圖表前的段落中。
請求應獲得哪些區塊
根據問題調整頁面:
-
「問題是什麼」、除錯、修復 Bug: 首先放問題區塊(
references/writing.md),包含一個 Bug 的泳道圖(在主頁面上為可播放的,references/playable.md)。然後再加上解釋所需的任何其他泳道圖。 -
在任務討論過後實作功能或修復 Bug: 在問題區塊正下方放一個任務區塊(
references/page.md,「任務區塊」)。當使用者還在釐清問題時,尚無任務,因此沒有任務區塊。 -
「這是如何運作的」、「這個專案是做什麼的」: 沒有問題區塊,沒有任務區塊。一個流程的泳道圖,輔以必要的簡短段落。
-
「我要如何建構類似的東西」: 一個區塊:常見的泳道圖,可以加入哪些額外功能,以及如何進行。
-
任何與其他頁面連結的頁面(主頁面與其說明頁面,或使用者要求連結的頁面):在最底部放一個連結頁面區塊(
references/page.md,「連結頁面區塊」)。
其他任何情況:用最少區塊回答問題。
圖表:僅限泳道圖
只有兩種圖表:
- 泳道圖: 一個流程圖,每個參與者或系統一個盒子,步驟放在執行它們的盒子內,當工作轉移時箭頭穿過盒子(
references/diagrams.md)。 - 可播放的泳道圖: 相同的泳道圖,附有「重置 / 上一步 / 下一步 / 播放」按鈕、每次按壓一個箭頭,以及下方的說明文字(
references/playable.md)。「可播放」、「可播放的泳道圖」、「可播放的圖表」和「可播放的前後對比」都指這個。「泳道圖」單獨出現時指的是普通版本。
任何其他圖表請求(「Mermaid 圖表」、「畫出流程」、「這個的圖表」)都會獲得一個泳道圖。
工作流程
- 這是主頁面的說明頁面嗎? 在工單的資料夾中 grep 一個請求中的獨特詞語,即使使用者只貼上了一項文字且從未提及主頁面。如果符合,新頁面就是該主頁面的說明頁面:使用主頁面的檔名前綴,並在同一次變更中雙向連結(
references/page.md)。 - 建立檔案(
references/page.md,「檔案」),從assets/template.html複製而來。填入{{…}}佔位符,並將localStorage鍵toc-open-CHANGE-ME改為該頁面唯一的值。 - 決定區塊,根據「請求應獲得哪些區塊」,並只撰寫這些區塊。
- 繪製泳道圖(
references/diagrams.md)。在渲染之前,列出涵蓋程式碼中的每個迴圈、分支、失敗路徑和早期返回,並檢查每個都已繪製。 - 連結每個檔案參考,使用
#L<行號>。檢查每個路徑都存在,且每個目標行確實如文字所述。 - 執行下方檢查,然後在聊天中回報頁面的連結(見下方)。如果程式碼的任何部分沒有在圖表中畫出來,請在回覆中說明。
完成前的檢查
- 頁面只有請求所需的區塊:沒有解釋問題時的「問題區塊」,沒有討論任務時的「任務區塊」,沒有被要求時的表格,圖表下方沒有任何東西。
- 當頁面解釋某人說了什麼或想要什麼時,其第一句以使用者會用的詞語說出他們想要什麼(
references/writing.md,「解釋某人的意思」)。 - 頁面保持模板的外觀:始終深色,所有顏色來自
references/DESIGN.md,每個連結都是帶有相應標記的藍色藥丸,沒有重新加入prefers-color-scheme淺色主題(references/page.md,「外觀」)。 - 圖例說明的是意義而非顏色(「哪裡出了問題」,而非「赭色 = …」);頁面沒有自己的顏色列表(
references/page.md)。 - 每個圖表都是泳道圖:頁面沒有
sequenceDiagram、stateDiagram、classDiagram或其他圖表類型。 - 使用 mermaid-cli 渲染每個圖表並查看 PNG(
references/diagrams.md,「渲染以檢查」)。頁面必須能載入且無 Mermaid 語法錯誤。 - 每個發送、寫入、呼叫或讀取的盒子,其文字中都要說明發送到哪裡或從哪裡來,且其箭頭終止於該系統的盒子。對另一個系統的每個呼叫都是一個向外箭頭,若下一步驟使用該回應,則再加上一個返回箭頭。
- 泳道圖泳道:在原始碼中 grep
[" "]和ghost;必須沒有。在 PNG 中,沒有泳道盒子比其步驟所需更寬或更高。 - 可播放的泳道圖:在瀏覽器中從頭到尾逐步播放並返回。
- 每個側邊欄的
href和data-href都能解析到頁面上的一個id,且每個檔案連結的路徑相對於頁面都存在。 - 說明頁面:主頁面在其討論主題的任何地方都連結到它,且說明頁面的開頭會返回連結。
- 連結頁面:每個頁面都在其「連結頁面」區塊中列出另一個頁面,該區塊是頁面的最後一個區塊,且其中的每個連結都打開一個現有檔案。
- 更改任務狀態後:一次 grep 列出每個任務的 checkbox 類別和標籤,且所有完成的任務看起來一致(
references/page.md)。 - 由自動化開啟的瀏覽器分頁通常處於背景(
document.visibilityState === "hidden"),因此滾動事件不會觸發。請透過每次scrollIntoView()後呼叫markActive()來測試滾動監控,不要認為它壞了。
在聊天中提及頁面
每當聊天回覆提及一個 HTML 頁面時,給出使用者可以直接貼到瀏覽器網址列的兩行文字,每行單獨一行:
file:///Users/<你>/<倉庫>/_<主題>/<主題>.html
/Users/<你>/<倉庫>/_<主題>/<主題>.html
第一行是完整的 file:/// URL,第二行是磁碟上的絕對路徑。這兩行上不能有其他任何東西:沒有散文、沒有反引號、沒有 markdown 連結、沒有項目符號、沒有 > 引用區塊。如果需要,可以在上方放一個簡短標籤(「將此貼到您的瀏覽器中:」)。當您指的是某個區塊時,在確認 id 存在後,將該區塊的 #id 加到 URL。聊天中的程式碼檔案則保留常見的相對連結。
原因: 相對連結會在 VS Code 中打開 HTML 原始碼,而 file:/// 連結會在瀏覽器中打開渲染後的頁面。埋在句子中或包在 markdown 裡面的 URL 必須手動挑選出來。