cover

從 Hexo 到 Quartz（下）：搬家技術細節與踩坑

上篇講了為什麼搬和怎麼選，這篇來聊實際怎麼搬兩百多篇文章，以及 Quartz 的設定細節。

先講結論

搬兩百多篇聽起來恐怖，但用 AI 輔助批次處理 frontmatter 和格式轉換，省了大概 80% 的時間。最花時間的反而是「重新審視哪些文章值得搬」這件事。

搬家的實際步驟

Frontmatter 轉換

Hexo 和 Quartz 的 frontmatter 有幾個關鍵差異：

abbrlink 不需要了（Quartz 用檔案路徑當 URL）
index_img 要換成 Quartz 的圖片處理方式
categories 的巢狀陣列要攤平
date 格式統一成 YYYY-MM-DD

手動改兩百多篇？別鬧了。我用 AI 寫了腳本批次處理——frontmatter 轉換、自動補 description、分類映射、wikilink 建議，全部一次搞定。

圖片路徑大搬遷

這是最惱人的一步。我把所有圖片集中到 content/static/images/ 下，按分類建子資料夾，用腳本批次替換文章中的圖片路徑。暴力但有效。

兩百多篇品質參差怎麼辦？

我分了三級：

A 級（直接搬）：內容完整有參考價值，約 60 篇
B 級（改了再搬）：主題有價值但需要重寫補充，約 80 篇
C 級（先不搬）：過時、太短、或已被其他文章覆蓋

先把 A 級搬過去讓網站能用，B 級慢慢改，C 級看心情。你不需要一次搬完，這是我最重要的心得。

Quartz 設定重點

quartz.config.ts

核心設定檔用 TypeScript 寫，有型別提示，改起來比 Hexo 的 _config.yml 舒服很多：

const config: QuartzConfig = {
  configuration: {
    pageTitle: "你的網站名稱",
    enableSPA: true,           // 單頁應用模式
    enablePopovers: true,      // hover 預覽連結內容
    locale: "zh-TW",
    baseUrl: "your-username.github.io",
  },
  plugins: {
    transformers: [
      Plugin.ObsidianFlavoredMarkdown({
        enableInHtmlEmbed: false,
      }),
      Plugin.CrawlLinks({
        markdownLinkResolution: "shortest",
      }),
    ],
  },
}

CrawlLinks 的 markdownLinkResolution: "shortest" 很重要——它讓你用最短的檔名就能連結到文章，[[closure]] 就能連到 javascript/closure.md，不用寫完整路徑。

Layout 自定義

quartz.layout.ts 控制頁面區塊配置，右側放 Graph + TOC + Backlinks 是我覺得最實用的組合：

export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  right: [
    Component.Graph(),          // 知識圖譜
    Component.TableOfContents(),
    Component.Backlinks(),      // 反向連結
  ],
}

Backlinks 設定 showContext: true 可以讓讀者不用點進去就看到「哪篇文章的哪段話引用了這篇」。

搬家踩坑紀錄

這些坑我都踩過，你就不用再踩了：

中文檔名：雖然 Quartz 支援，但建議用英文，避免 URL encode 各種鬼問題
圖片路徑是相對於 content 根目錄：不是相對於文章位置，跟 Hexo 不同
frontmatter 的 date 格式：統一用 YYYY-MM-DD，帶時間的格式偶爾會出問題
SPA 模式下的外部連結：開了 enableSPA: true 要確認外部連結有 target="_blank"
Mermaid 圖表的中文標點：某些特殊標點會造成渲染錯誤，debug 到懷疑人生

給想搬家的人

三句話總結：

先搬 10-20 篇最好的文章，確認一切正常再搬剩下的。一次搬完你會被格式轉換淹沒然後放棄
重複性工作讓 AI 做，你的時間花在「重新組織知識架構」和「建立文章連結」上
搬家是重新整理知識的好機會——哪些文章過時了？哪些主題值得擴充？你的知識體系有哪些缺口？搬完你會對自己的知識庫有全新的認識

記得設定 redirect。舊部落格被搜尋引擎收錄的話，做好轉址（GitHub Pages 的 _redirects 或 meta refresh），不然辛苦累積的 SEO 就白費了。

搬家搬到一半發現自己以前寫的文章真的很爛，~~這算是意外收穫嗎~~。

Terry Yao's Blog

分類

目錄

從 Hexo 到 Quartz（下）：搬家技術細節與踩坑紀錄