新增部落格文章
目標
將使用者內容新增到現有的靜態部落格,而不強制使用新的部落格系統。
此技能必須先了解目前網站如何呈現文章,然後以該風格新增新內容。它不是一個通用的 Markdown 轉 HTML 轉換器。
合約
輸入:
- 現有的靜態網站資料夾及其當前的文章/索引/範本系統。
- 一或多篇來源文章:Markdown、Obsidian 筆記、Word 文件、舊的 HTML、貼上的文字、圖片、附件或內容資料夾。
- 可選的元資料,例如標題、日期、標籤、摘要、代稱、封面圖片和匯入範圍。
輸出:
- 與網站現有文章風格相符的新文章/詳細頁面。
- 已更新的入口點,例如部落格索引、彙整、標籤/分類、首頁近期文章、搜尋資料、RSS 或網站地圖(如果這些系統已存在)。
- 已複製/重新連結的本機圖片和附件,並使用相對於頁面的路徑。
- 適用的情況下,已更新
EDITING.md文章說明。
邊界:
- 不要重新設計網站,或在現有系統明確時建立新的文章系統。
- 不要發明來源不支援的元資料、日期、作者或主張。
- 不要靜默地新增遠端數學/CDN 依賴。
- 不要發布;請使用
publish-static-site。
成功閘道:
- 新文章以現有風格呈現,並可從適當的索引中存取。
- 圖片、數學公式、連結、程式碼、表格和豐富內容可正常運作,或明確回報未解決的項目。
- 路徑是相對於文章和索引頁面的頁面相對路徑。
- 受影響的頁面通過瀏覽器驗證,且
review-static-site可以通過或僅回報可接受的限制。
若閘道失敗:
- 在此技能中修正轉換、元資料、路徑、資源或索引連線。
- 對於因匯入導致的小型視覺修復,使用
edit-site-part。 - 修復後再次使用
review-static-site。
使用時機
當使用者想要以下情況時,使用此技能:
- 新增一篇新文章、筆記、隨筆或部落格文章。
- 將幾個 Markdown 檔案匯入靜態網站。
- 將文章從舊部落格移至新產生的網站。
- 將貼上的文章文字轉換為網站文章頁面。
- 更新部落格索引、彙整、標籤、首頁近期文章或相關入口點。
- 在新增內容的同時,保留目前網站的視覺語言。
請勿使用此技能來選擇主題、從頭建立新網站、重新建立網站的風格、個人化個人資料/關於內容、進行微小的視覺調整、發布網站或將專案轉換為框架。
輸入
使用可用的任何資訊:
- 靜態網站資料夾,通常是
site/、dist/、out/或public/。 - 一或多個 Markdown 檔案、Word 文件、貼上的文章、舊的 HTML 檔案、圖片資料夾或內容資料夾。
- 來自先前技能的
EDITING.md、頁面地圖或交接說明。 - 現有的文章範本頁面或代表性文章。
- 使用者提供的標題、日期、標籤、分類、摘要、代稱、封面圖片和發布偏好。
- 是否匯入所有文章、選定的子集或先匯入代表性批次。
如果來源內容很大,請先檢查結構,避免盲目匯入所有內容。
1. 了解現有的文章系統
在撰寫新文章之前,請檢查網站的運作方式。
檢查:
- 文章檔案,例如
posts/*.html、notes/*.html、articles/*.html或巢狀路由資料夾。 - 索引頁面,例如
blog.html、archive/index.html、notes/index.html、tags/index.html或category/index.html。 - 資料檔案,例如
data/posts.json、data/notes.json、data/site.json或profile.json。 assets/script.js或類似檔案中的 JavaScript 資料陣列。- 首頁區段中的近期文章、精選文章、筆記、閱讀清單或寫作亮點。
- 可作為範本的現有文章/詳細頁面。
- 現有路徑策略:範本是否使用頁面相對連結,例如
../assets/style.css或伺服器根目錄連結,例如/assets/style.css。 - 如果已存在,檢查 RSS、Atom、網站地圖、搜尋索引或標籤/分類頁面。
- 用於新增文章的
EDITING.md說明。 - 現有的圖片和附件約定,例如
assets/images/posts/、同位置的貼文資料夾、封面欄位、圖形類別、燈箱標記、標題或回應式圖片包裝器。 - 現有的豐富內容約定,例如數學渲染、程式碼高亮、表格、腳註、提示區塊、標題錨點、目錄、連結卡片、嵌入、圖表和引用/參考文獻區段。
遵循現有結構。當網站已有文章系統時,不要發明新的。
2. 提取文章元資料
對於每篇來源文章,提取或推導:
- 標題。
- 日期。
- 代稱。
- 標籤或分類。
- 摘要或節錄。
- 封面圖片或英雄圖片(如果存在且可用)。
- 來源路徑。
- 閱讀時間,僅在目前網站已使用或易於一致計算時使用。
若存在,請使用 Frontmatter。否則從第一個標題、檔案名稱、周圍資料夾、可見的日期文字或第一段推斷。
不要發明具體的日期、標籤、作者或主張。如果某個欄位缺失且無法推斷,請使用明確的佔位符,或在網站風格允許時省略該欄位。
3. 將內容轉換為網站風格
透過比對現有文章範本和閱讀體驗來建立新的文章頁面。
保留:
- 頁首、導覽、頁尾、側邊欄和共享外殼。
- 文章排版、間距、元資料佈局、標籤、返回連結和相關連結。
- 任何特殊的主題語言,例如日誌條目、田野筆記、卡片、終端機/彙整框架或簡潔的隨筆。
- 現有的 CSS 類別慣例和資料結構。
對於 Markdown:
- 將標題、段落、區塊引用、清單、任務清單、表格、程式碼區塊、連結、腳註、提示區塊和圖片轉換為語意化的 HTML。
- 保留程式碼語言標籤(如果可用)。
- 保持圖片引用為頁面相對路徑,並僅在需要時複製本機圖片。
- 將中文、日文、韓文、帶重音符號的拉丁文和其他非 ASCII 文字保留為可讀的 UTF-8。
對於舊的 HTML:
- 提取文章主體和元資料。
- 移除舊網站的 chrome、分析、評論、不相關的導覽和來源網站身份。
- 將內容重新包裝在新網站的文章範本中。
3.5. 保留靜態路徑相容性
新增文章時,從每個產生的頁面位置計算路徑。不要盲目地將 index.html 的路徑複製到巢狀文章頁面。
預設規則:
- 新的文章頁面應使用頁面相對連結來連結共用的 CSS、JavaScript、字型、圖片和導覽。
- 如果文章產生在
posts/my-post.html,共享資源通常需要../assets/style.css、../assets/script.js以及文章圖片,例如../assets/images/posts/my-post/figure.png。 - 從根頁面到文章的連結通常應為
posts/my-post.html。 - 從文章回到根頁面的連結通常應為
../index.html、../blog.html或../archive/index.html,具體取決於結構。 - 除非現有網站有意使用根絕對路徑(例如
/assets/...、/posts/...、/data/...或/images/...),且使用者接受直接以file://開啟和子路徑託管可能失效,否則不要引入根絕對路徑。 - 使用相同的路徑策略更新 JavaScript 產生的連結、搜尋結果、標籤篩選器、相關文章連結、封面路徑、RSS/網站地圖條目以及任何資料檔案。
- 如果現有網站意外使用了根絕對路徑,請回報並優先修復受影響的路徑,而不是擴大問題。
避免本機檔案擷取問題:
- 不要讓新新增的文章依賴
fetch()來擷取本機 JSON/Markdown 作為文章主體。 - 如果索引是從資料渲染的,請在 HTML 中保留必要的文章連結,或使用可與直接開啟預覽搭配運作的相對 JavaScript 資料物件。
4. 處理豐富內容格式
有目的地保留豐富內容,而不是將所有內容扁平化為純文字段落。
首先檢查目前網站是否已支援:
- 使用 KaTeX、MathJax、自訂 CSS 或原始 TeX 區塊進行數學渲染。
- 程式碼高亮、語言標籤、複製按鈕或終端機風格的程式碼框架。
- 表格、回應式表格包裝器、腳註、提示區塊、告示、引文和任務清單。
- 標題錨點、目錄、反向連結、相關筆記或章節連結。
- 連結卡片、書籤清單、URL 索引頁面、引用、參考文獻清單或參考書目區段。
- 嵌入媒體,例如影片、音訊、PDF、iframe、Mermaid 圖表、Excalidraw/SVG 圖表或可下載的附件。
當存在現有模式時,請遵循它。如果沒有模式,請使用簡單的語意化 HTML,並回報任何需要額外渲染器的功能。
數學公式:
- 保留來自
$...$、$$...$$、\(...\)、\[...\]或 Word 方程式匯出的行內和顯示數學公式。 - 如果存在,請使用網站現有的數學渲染器。
- 如果來源包含許多公式且沒有渲染器,對於純靜態網站,偏好使用本機 KaTeX 整合:將 KaTeX CSS/JS/字型儲存在本機供應商資料夾中,新增一個小型本機渲染腳本,且不要依賴 CDN。
- 不要靜默地將遠端 MathJax/KaTeX 依賴項新增到原本無依賴的網站。
- 在標記為數學的元素中保留原始 TeX 作為備用,然後在瀏覽器中渲染它。如果某個公式渲染失敗,可讀的 TeX 備用內容應保持可見,而不是破壞頁面。
- 標準化 KaTeX 需要的明顯來源語法,例如 softmax 箭頭、
\cdot、\times、意外混入公式的標點符號以及常見的 Q/K/V 表達式。 - 在新增數學渲染器後,不要讓包含大量公式的文章看起來像程式碼般的 TeX 方塊。
- 在原始碼和瀏覽器備用內容中保持公式可讀。
程式碼區塊:
- 保留圍欄程式碼語言名稱。
- 在程式碼區塊內跳脫 HTML。
- 保持長程式碼行可捲動,而不是破壞頁面佈局。
- 重複使用現有的程式碼區塊樣式、複製按鈕和語法高亮慣例。
- 不要執行文章中的原始碼。
表格:
- 將 Markdown、Word 或 HTML 表格轉換為語意化的表格。
- 將寬表格包裝在網站現有的回應式表格容器中,或新增一個小型本機包裝器。
- 保留標題行、對齊意圖和標題(如果可用)。
連結、URL 索引和內部引用:
- 保留具有清晰連結文字的外部連結。
- 當目標文章被匯入時,將相對連結和 Markdown
.md連結轉換為產生的靜態 HTML 路徑。 - 將 Obsidian wikilinks(例如
[[Note]]、[[Note#Heading]]和[[Note|Alias]])轉換為正常連結(當目標可解析時)。 - 將未解析的內部連結保留為可見的佔位符或純文字,並回報它們。
- 當網站使用錨點連結或目錄時,產生穩定的標題 ID。
- 對於 URL 索引、書籤或連結彙整文章,保留清單結構。如果存在,請使用網站現有的連結卡片/清單樣式;除非使用者要求,否則不要發明需要擷取遠端元資料的預覽卡片。
腳註、引用和參考文獻:
- 如果存在,使用網站現有的風格將 Markdown 腳註轉換為腳註區段。
- 保留引用標籤、參考書目條目和參考文獻連結。
- 如果來源文字使用未解析的引用鍵(例如
[@paper2024]),請保持它們可見,並回報引用元資料缺失,除非提供了參考書目檔案。
提示區塊、告示和區塊類型:
- 將 Obsidian/GitHub 風格的提示區塊(例如
> [!NOTE]、> [!TIP]、> [!WARNING]和> [!IMPORTANT])轉換為網站最接近的提示區塊/卡片/區塊引用模式。 - 當目前網站有核取清單樣式時,將任務清單保留為核取清單;否則使用停用的核取方塊標記或純文字清單。
嵌入和附件:
- 對於 PDF、簡報、資料集、下載、音訊和影片,除非網站已嵌入該媒體類型,否則偏好使用清晰的連結或下載卡片。
- 僅在使用者提供時才複製本機附件。
- 僅在使用者擁有或有意引用時才保留遠端嵌入。
- 對於 Mermaid 或圖表區塊,如果存在現有渲染器,請使用它。如果沒有渲染器,請保留來源區塊並回報,或僅在實用且適當的情況下轉換為靜態 SVG/PNG。
5. 處理文章圖片和資源
根據目前網站的資源慣例處理圖片。
首先檢查現有文章如何儲存和呈現圖片:
- 共享資源資料夾,例如
assets/images/posts/<slug>/。 - 同位置的文章資源,例如
posts/<slug>/images/。 - 資料欄位,例如
cover、heroImage、thumbnail或images。 - 圖形標記、標題、燈箱連結、延遲載入、寬度/高度屬性和回應式 CSS 類別。
偏好現有模式。如果沒有模式,請使用簡單的靜態慣例,例如:
assets/images/posts/<post-slug>/
對於 Markdown 來源:
- 從 Markdown 檔案的資料夾解析相對圖片連結。
- 在需要時將本機圖片複製到網站的文章圖片資料夾中。
- 將 Markdown 圖片引用重寫為新的相對網站路徑。
- 對於巢狀文章頁面,在圖片路徑中包含正確的
../深度。 - 保留 Markdown 中的替代文字(如果存在)。
- 如果來源使用附近的斜體文字、標題屬性或 Obsidian 風格的嵌入,請轉換圖片標題。
- 不要留下指向絕對本機磁碟路徑的連結。
對於 Obsidian 筆記:
- 支援常見的嵌入,例如
![[image.png]]和相對附件資料夾。 - 搜尋筆記附近的可能附件資料夾,例如
attachments/、assets/、images/,或可見的儲存庫設定附件資料夾。 - 將嵌入重寫為正常的 HTML 圖片或圖形標記。
對於 Word .docx 來源:
- 從文件套件中提取嵌入的圖片,或使用可用的文件工具。
- 在可能的情況下,相對於周圍文字保留圖片順序。
- 將提取的圖片儲存在文章圖片資料夾下,並使用穩定的名稱。
- 當可用時,使用附近的標題或替代文字作為圖片的 HTML
alt屬性。 - 不要重複提取相同的圖片。