譜牒典藏與發布規則

為何採混合方式

本站不在 PDF 與 JPG 之間二選一,而採「原件+閱覽本」:

  • PDF、原始 JPG、TXT、CSV、MD 是原始或校閱憑據,完整保留,不得被轉檔覆蓋。
  • PDF 逐頁轉成最寬 1600px、品質 80 的漸進式 JPEG,原始 JPG 也另產生同規格預覽。
  • 網頁一次只載入目前頁,並預載下一頁;不會一進頁面就下載整部 48 頁 PDF 或全部圖像。
  • 閱讀器支援上一頁、下一頁、頁次選擇、鍵盤方向鍵、縮放、PDF 原件及 JPG 原圖。

這樣可兼顧手機閱讀、GitHub Pages 靜態部署、原件查核及未來搬遷。JPEG 是可刪除重建的快取,不是母資料。

檔案與 ID

00-原始資料/族譜掃描/            ← 原始檔,永不反向修改
data/archive-catalog.yaml        ← 穩定 collection/document ID 與顯示名稱
scripts/archive/build-archive.mjs
        ↓
quartz/static/archive/           ← 建置產物,gitignored
        ↓
public/static/archive/           ← 本次網站輸出
  • 典藏組使用 ARC-C...,譜冊使用 ARC-D...,影像集使用 ARC-A...。
  • 已寫入目錄的 ID 不得因改名、換封面或搬動顯示順序而更改。
  • 未設定的 PDF 會依路徑產生暫定 ID;正式整理時應補回目錄,避免日後改檔名造成 ID 變動。
  • 同一資料夾內未列入設定的 JPG、TXT、CSV、MD 仍會自動收錄,避免漏件。

本機與公開版

  • npm.cmd run build:dev:本機完整校閱,包含原始 PDF、JPG 與所有轉錄附件。
  • npm.cmd run build:site 或 npm.cmd run build:family:親友密碼完整版。輸出全部人物、戶籍內容、PDF、JPG 與轉錄附件,再由 JavaScript 共用密碼提供簡易入口門檻。
  • npm.cmd run build:public:公開遮罩版。只有 data/archive-catalog.yaml 中明確標示 publish_public: true 的典藏組才會輸出原件。
  • 新增資料仍預設 publish_public: false,保留未來切回公開遮罩版時的發布分類;此欄不限制親友密碼完整版。
  • 2026-08-12 資料持有人明確決定:目前 GitHub Pages 採完整親友版,不做人物匿名、頁面過濾或典藏過濾,只保留 JavaScript 共用密碼 family。這不是加密;知道靜態網址的人仍可能直接取得 HTML、JSON、PDF、JPG、TXT、CSV 與 MD。
  • 2026-08-15 補充:完整史料的研究與族人查閱價值優先,不對戶籍原文、考據、事件或原始附件逐項遮罩。網站以全站 HTML noindex, nofollow、關閉 sitemap/RSS 及禮貌門降低非預期曝光,不宣稱能阻止直接網址存取。

未來增加其他家族

  1. 在 00-原始資料/族譜掃描/ 建立新的家族或典藏子目錄。
  2. 在 data/archive-catalog.yaml 新增 collection,給予永不重用的 ID、年代、說明及譜冊 ID。
  3. 執行 npm.cmd run build:dev,確認頁數、封面、附件與順序。
  4. 執行 node scripts/archive/archive-smoke.mjs 與 RWD 測試。
  5. 若要讓資料在「公開遮罩版」中也出現,人工確認著作權與公開範圍後,才可將該 collection 改為 publish_public: true。

GitHub Pages 容量邊界(2026-08-14 核對)

GitHub 官方目前建議 Pages 來源 repo 不超過 1 GB,發布站點也不得超過 1 GB;一般 Git 單檔超過 50 MiB 會警告,超過 100 MiB 會阻擋,而且 Git LFS 不能用於 GitHub Pages。

目前本機完整典藏輸出約 97 MB(69 個檔案),可繼續使用 GitHub Pages。擴展時採以下分級:

  • 站點低於 500 MB:維持原件+閱覽本。
  • 500–800 MB:降低預覽尺寸、把少用附件改為按需外部封存,並監測部署時間。
  • 接近 800 MB 或單件可能超過 100 MiB:原件轉移到可長期保存的物件儲存/數位典藏庫;Pages 只留目錄、封面、預覽與永久連結。

參考:GitHub Pages limits、About large files on GitHub、About Git Large File Storage。