GPT Pages Importer：將 Pages 視覺化與完整 HTML 帶到 Obsidian 的流程示意

GPT Pages Importer for Obsidian

English · 繁體中文

把 Pages 的圖表與互動，帶進你的 Obsidian 筆記。
完整 HTML・精準配對・自動清理・備份保護

Build and tests Version 0.2.5 Pairing formats v3, v2 and v1 MIT License Node.js 24

快速開始 · 使用指南 · 配對格式 · Page 生成技能

--- Pages 負責呈現想法，Obsidian 負責收藏與延伸。這個外掛把匯出的 Markdown 與完整、可攜的 HTML 原始碼（portable HTML source）接起來：驗證圖表配對，將頁尾來源移回圖表位置，清除已確認的標記與原生圖片參照。 > **目前發行版本為 [0.2.5](https://github.com/DLeungDL/obsidian-gpt-pages-importer/releases/tag/0.2.5)。** 已上架 [Obsidian 社群目錄（Community directory）](https://community.obsidian.md/plugins/gpt-pages-importer)，亦可手動安裝；已完成的桌面驗證與其他平台的實測範圍，見[相容性紀錄](docs/compatibility.zh-TW.md)。互動 HTML 需選用的 Polyglot Renderer，並由使用者明確確認信任。 ## 0.2.5 新功能（What's new） - **更可靠的 MathBox 匯出**：生成技能將完整、版本相符的 MathBox CSS 與授權聲明內嵌至 HTML，圖表不再依賴額外的樣式表請求。 - **JavaScript CDN 備援（fallback）**：相容且固定版本的 Three.js、OrbitControls 與 MathBox 先從主要 CDN 載入，失敗時再嘗試備援來源；設有逾時與明確錯誤訊息。JavaScript 依賴仍需要網絡，使用 WebGL 的圖表亦需要環境支援。 - **技能亦需更新（Skill update）**：請更新 AI 代理中的技能，才能使用改善後的版型。只更新 Obsidian 外掛不會重寫既有 Page 或已匯出的 HTML；受影響圖表需用新版技能重新產生，再匯出及匯入。
較早更新 · 0.2.0–0.2.4 ## 0.2.4 新功能（What's new） - **公式清理修正**：自動清理現在支援圍欄符號與 `latex` 之間的 CommonMark 空格／Tab，與手動匯入一致。保留原有完整備份、重複處理及 HTML 信任行為。 - **匯出指引**：公式檢查清單確認技能產生的裸 `latex` 區塊，再於匯入時加入 Obsidian 數學分隔符。 ## 0.2.3 新功能（What's new） - **Pages 公式匯入 Obsidian**：將完整、獨立且內含裸 TeX 的 `latex` 區塊轉成原生 `$$` 數學公式。支援手動匯入與資料夾清理；關閉 HTML 渲染時，亦可處理只有公式的筆記。預覽及清理摘要顯示轉換數量，沿用原有備份與衝突保護。 - **修正公式技能**：Page 公式使用不加錢符號包裹的裸 `latex` 區塊。刻意展示原始碼時可用 `tex`、`text` 或 `latex source`；巢狀、未關閉、已有數學分隔符及辨識到的完整文件／前置指令會保留。[公式流程與驗證範圍](skills/gpt-pages-obsidian-visualizations/references/math.md)。 ## 0.2.2 新功能（What's new） - **視覺化技能（Visualization skill）**：一般圖表預設用 Plotly.js，數學幾何與概念動畫用 MathBox，允許固定版本 CDN。新範例提供載入／錯誤提示及可調控制項；CDN 圖表需要網絡，離線依賴檢查仍可選用。 - **技能整理（Skill cleanup）**：移除舊 `generate-portable-page` 別名。請使用 `$gpt-pages-obsidian-visualizations`，並在 AI 代理端分別更新技能。新範例已通過自動化靜態／模擬測試，尚未重新在 Pages 與 Obsidian 實際運行。 ## 0.2.1 新功能（What's new） - **簡體中文介面（Simplified Chinese）**：命令、匯入表單、預覽、設定、渲染器狀態與診斷訊息會跟隨 Obsidian 的「简体中文」設定。Obsidian 1.8.7 起，選擇「简体中文」並依提示重新載入即可套用；支援 `zh`、`zh-CN`、`zh-Hans`、`zh-SG`，並保留原有英文及繁體中文支援。 ## 0.2.0 新功能（What's new） - **可攜圖片（Portable images）**：從單一 Markdown 匯出檔中的圖片來源區塊還原 PNG、JPEG、GIF、WebP。驗證後保存至筆記旁的 `GPT Pages Assets/`，改為本地連結；重複匯入會復用相同圖片。支援手動匯入與資料夾清理，限制為**每張 1 MiB、合計 4 MiB、最多 32 個圖片來源區塊**。[圖片製作與復原指南](docs/images.zh-TW.md)。 - **跨 Page 連結（Cross-Page links）**：新版技能在匯出前，將內部連結解析為工具確認的 HTTPS 網址。連結仍指向線上 Page，需要目標存取權，不會變成本地筆記；未解決的連結保留並報告。[連結檢查指南](skills/gpt-pages-obsidian-visualizations/references/page-links.md)。 - **公式製作（Math authoring）**：目前來源中的技能使用裸 `latex` 公式區塊供 Pages 顯示，再將符合條件的區塊轉為 Obsidian 數學公式。此流程需要 0.2.3 或更新的匯入器；0.2.2 及以前仍保留為程式碼。[公式流程](skills/gpt-pages-obsidian-visualizations/references/math.md)。 **Obsidian 外掛與 AI 代理中的技能需分別更新。** 圖片與原生數學公式不需要 HTML 信任或 Polyglot Renderer。跨 Page 與多圖片範例已通過手動驗證；公式渲染已在修正後的本地筆記驗證，未修改的 Page 公式匯出仍需另做端到端驗證（end-to-end validation）。
## 為什麼使用它？ 提供英文、繁體中文與簡體中文介面：Obsidian 1.8.7 起跟隨應用程式語言，繁體中文使用 `zh-TW`／`zh-Hant`，簡體中文使用 `zh`／`zh-CN`／`zh-Hans`（亦支援 `zh-SG`），未支援語言使用英文。切換 Obsidian 語言並依提示重新載入後套用。Obsidian 1.5.0–1.8.6 使用英文介面；最低支援版本仍為 1.5.0。 | | 能帶走的內容與工作流程 | | :--- | :--- | | **圖表保留（Portable visuals）** | 保存完整 HTML、CSS、JavaScript 與資料，讓互動圖有可攜的原始碼。 | | **精簡配對（Compact pairing）** | v3 正文只留短 ID，參照與 SHA-256 集中頁尾；驗證後把 HTML 移回各圖位置。 | | **資料夾清理（Folder cleanup）** | 監看指定資料夾及所有子資料夾，可一次放入多個 Markdown，自動原地處理。 | | **寫入保護（Protected writes）** | 純文字預覽、修改前備份、重複匯入不重寫，本機修改有衝突保護。 | | **明確信任（Explicit trust）** | 手動匯入預設保存為 `html-source`；經確認後才產生供 renderer 執行的 `html`。 | | **AI 生成流程（AI authoring workflow）** | 匯入前先使用附帶技能，製作含配對 HTML 來源的 Page；提供版型、標記生成器與匯出原碼驗證工具。 | ## 快速開始（Quick start） 互動圖表流程需要以下三個部分： | 元件（Component） | 用途 | | :--- | :--- | | **Pages ＋ 生成技能（Authoring skill）** | 匯出前準備完整 HTML、v3 配對與可攜來源。 | | **GPT Pages Importer** | 在 Obsidian 資料庫中驗證並還原匯出內容。 | | **Polyglot Renderer** | 顯示已信任的互動 HTML；還原圖片與原生公式不需要它。 | ### 1 · 在 AI 代理中使用生成技能 **前置需求（prerequisite）：在 AI 代理（AI agent）中啟用並連接 [Pages 外掛](https://chatgpt.com/plugins/plugin_connector_1p_4a72ddeef4c481918f92d8e8df18fb2c?open_in_app)，再選取 `@Pages`。** 代理必須能使用 Pages 的讀寫及原生視覺化工具。此技能要求建立或更新 Page 時使用 Pages 工具；若工具不可用或無法存取目標 Page，請先完成連接或取得存取權，再繼續操作。 將完整的 [`skills/gpt-pages-obsidian-visualizations/`](skills/gpt-pages-obsidian-visualizations/) 資料夾加入代理的技能庫，包含 scripts、references 與 assets。如果代理透過檔案讀取指引，請指定其中的 [SKILL.md](skills/gpt-pages-obsidian-visualizations/SKILL.md)，並保留其連結的資源供代理使用。匯出前，先搭配 Pages 使用技能準備 Page。 以 `npm ci --ignore-scripts --prefix ` 安裝技能工具鎖定版本的解析器依賴（parser dependencies）。[跨 Page 連結檢查](skills/gpt-pages-obsidian-visualizations/references/page-links.md)會在匯出前，將可解析的內部連結改為 Pages 工具確認的 HTTPS 網址，保留連結文字並列出未解決項目。連結仍需帳號存取權，匯入外掛維持離線運作。 可直接使用以下提示詞（prompt）： ```text 使用 @Pages 與 $gpt-pages-obsidian-visualizations，建立或更新一個以［你的主題］為內容、可匯出 Markdown 至 Obsidian 的 GPT Page。請透過 Pages 工具寫入 Page 並建立原生視覺化。一般圖表預設用 Plotly.js，數學概念動畫用 MathBox；允許固定相容版本的 CDN，並標明需要網絡。正文保留原生視覺化與只含短 ID 的 v3 精簡標記，頁尾集中放置完整 HTML 原始碼、依賴網址、原生參照與 SHA-256；不得回退 v2。 有圖片時加入可攜圖片來源區塊，匯出前解析跨 Page 連結，公式使用獨立 latex 區塊，內含裸 TeX，不加入錢符號包裹；確認已安裝的匯入器支援轉為 Obsidian 公式。 ``` 技能會準備原生圖表、簡短圖表 ID，以及含對應參照（reference）與 SHA-256 校驗資訊的頁尾 HTML。這是本流程必要的製作步驟：一般 Page 匯出可能只有原生圖片參照，未包含可攜式 HTML，外掛無法還原缺少的來源。技能在 AI 代理中使用，GPT Pages Importer 則在 Obsidian 中處理產生的 Markdown。 0.1.6 起，技能與生成工具強制使用 v3，即使未知目標外掛版本也不回退；匯入器仍相容既有 v1／v2 匯出檔。一般 Page 保留 `html` 來源圍欄（code fence）；自動清理的信任流程測試另用 `html-source` Markdown 副本，HTML 位元組（bytes）與校驗值保持相同。確認資料夾信任後，按「儲存設定」（Save settings）才套用轉換。AI 代理中的技能資料夾需與 Obsidian 外掛分別更新。 ### 2 · 取得外掛 開啟 [Obsidian 社群外掛頁面](https://community.obsidian.md/plugins/gpt-pages-importer)，按 **Add to Obsidian**，在 Obsidian 內安裝並啟用 **GPT Pages Importer**。 如需手動安裝： 從 [GitHub Releases](https://github.com/DLeungDL/obsidian-gpt-pages-importer/releases/latest) 下載 `main.js`、`manifest.json` 與 `styles.css`，放入同一個 `gpt-pages-importer/` 資料夾。授權及第三方聲明已嵌入 `main.js`。
自行建置（Build from source） 需要 **Node.js 24** 與 npm： ```sh git clone https://github.com/DLeungDL/obsidian-gpt-pages-importer.git cd obsidian-gpt-pages-importer npm ci npm run check ``` 也可在成功的 [GitHub Actions 工作流程](https://github.com/DLeungDL/obsidian-gpt-pages-importer/actions/workflows/check.yml) 下載 `gpt-pages-importer` 建置產物（artifact）。
### 3 · 安裝到 Obsidian 將包含三個下載檔的 `gpt-pages-importer/`（自行建置則為 `dist/gpt-pages-importer/`）整個資料夾複製到： ```text 你的 vault/ └── .obsidian/ └── plugins/ └── gpt-pages-importer/ ├── main.js ├── manifest.json └── styles.css ``` 在 **設定 → Community plugins** 啟用 **GPT Pages Importer**。更新檔案後，重新載入外掛。 ### 4 · 從 Pages 下載 Markdown 1. 開啟使用技能準備好的 Page，點選左上角的頁面標題選單。 2. 按下圖紅色箭頭指向的 **下載（Download）**，將 Page 儲存為 Markdown（`.md`）檔案。 ![Pages 頁面標題選單，紅色箭頭指向「下載」](docs/assets/pages-download-zh-TW.png) 確認下載的 Markdown 包含圖表標記（markers），且各圖完整的 `html` 程式碼區塊已包含在頁尾。若缺少來源，請讓 AI 代理使用技能補齊 Page，再重新匯出。 有圖片時，另確認匯出包含 `gpt-pages-asset` 來源區塊，因為原生圖片參照不含圖片位元組。0.2.3 流程在 Pages 使用不含 `$`／`$$` 包裹的獨立 `latex` 區塊，再由支援此功能的匯入器轉為 Obsidian 公式；0.2.2 及以前不支援。請先檢查實際匯出檔，再啟用 HTML 渲染。 ### 5 · 匯入第一份筆記 1. 執行 **GPT Pages Importer: 匯入 Pages Markdown**，選取或拖入下載的檔案。 2. 查看目的地、成功配對數與警告，確認後寫入；目的筆記會自動開啟。 後續重匯同一 Page，沿用相同的來源識別名稱（source name）。完整流程與其他入口見[使用指南](docs/usage.zh-TW.md)。 需要使用互動圖表時，請安裝 Polyglot Renderer、檢查 HTML 並明確確認信任，詳見下方「閱讀、渲染與信任」。 ## 選擇你的工作方式 | | 手動匯入（Import） | 資料夾自動清理（Automatic cleanup） | | :--- | :--- | :--- | | **適合情境** | 預覽後建立或更新目的筆記 | 將一批匯出檔直接放入指定資料夾 | | **處理位置** | 預設建立於 `GPT Pages/` | 直接修改原檔，保留路徑與檔名 | | **重複處理** | 內容相同不寫入；本機修改停止覆寫 | 已清理內容不重寫，不新增備份 | | **HTML 語言** | 預設 `html-source`，信任後可輸出 `html` | 預設保留原語言，可另確認資料夾渲染信任 | | **備份** | 更新既有目的筆記前備份 | 每次原地修改前備份 | 設定自動清理時，填入一個監看資料夾（watched folder），即可涵蓋所有子資料夾。儲存並啟用後，會掃描既有文件，並處理之後新增、修改與移入的 Markdown。詳見[設定與信任流程](docs/usage.zh-TW.md#指定資料夾自動清理)。 ## 從 Page 到筆記 ```mermaid flowchart LR A["Pages
原生視覺化 + 短圖表 ID"] --> B["Markdown 匯出
正文標記 + 頁尾完整 HTML"] B --> C["驗證配對
ID · reference · SHA-256"] C --> D["Obsidian
HTML 回到圖表位置"] ``` 外掛從匯出檔讀取 HTML。只有唯一 ID、精確原生參照（reference）、完整來源與 SHA-256 全部通過，才清除該組標記及圖片參照；配對不明確時保留原文並警告。v1／v2 舊格式仍相容。 [閱讀 v3 配對契約 →](docs/format.zh-TW.md) ## 閱讀、渲染與信任 手動匯入預設將原始碼保留為 `html-source`。需要互動時，先檢查內容、明確信任，再配合獨立安裝的 [Polyglot Renderer](https://github.com/Nimaapr/polyglot-renderer) 呈現 `html`。 匯入視窗與自動清理的 HTML 渲染選項旁，會顯示 Polyglot Renderer「未安裝／未啟用／已啟用」。安裝或變更啟用狀態後，可按「重新檢查 renderer」。偵測讀取目前資料庫（vault）的安裝檔及已儲存啟用清單，不代表已成功載入或 renderer 設定正確；無法讀取或安裝不完整時顯示「無法確認」。狀態偵測不會代替信任確認、自動安裝／啟用外掛，或阻擋匯入與清理。 - 手動匯入的信任適用於**整份文件的 HTML 區塊**。 - 資料夾信任適用於該資料夾及子資料夾中，**現有與日後的所有 HTML 區塊**。 - 自動清理預設保留既有語言；關閉渲染選項不會還原已是 `html` 的區塊。 - 寫入前先備份；JavaScript 可能執行並發出網路請求。SHA-256 配對成功不代表程式碼安全。 [查看渲染選項、備份與還原 →](docs/usage.zh-TW.md) ## 隱私與存取（Privacy and access） 此外掛免費使用，不要求帳號、付款或 API 金鑰，不收集遙測資料（telemetry），也不自行發送網路請求。手動匯入會透過檔案選擇器讀取你選擇的 vault 外 Markdown；寫入僅限目前 vault 內的目的筆記、備份與外掛設定。自動清理只處理你指定的 vault 資料夾及子資料夾。 HTML 渲染由獨立安裝的 Polyglot Renderer 提供；你信任的 HTML／JavaScript 若包含外部圖片、字型、函式庫或請求，可能由 renderer 存取相應遠端服務。請在啟用信任前檢查完整內容。 0.2.0 起支援[單一 Markdown 可攜圖片](docs/images.zh-TW.md)：技能將原圖 Base64 放入明確的 `gpt-pages-asset` 來源區塊，外掛驗證後保存到筆記旁的 `GPT Pages Assets/` 並改寫成本地圖片連結。支援 PNG、JPEG、GIF、WebP，不需要 ZIP；只有原生圖片參照而沒有來源資料時無法還原。容量與復原規則見格式文件。此外掛不會連線 Pages 下載資產，也不提供雲端或雙向同步。 ## 文件與資源 | 想完成的事 | 從這裡開始 | | :--- | :--- | | 安裝、匯入、設定監看資料夾、重匯與還原 | [完整使用指南](docs/usage.zh-TW.md) | | 編寫或檢查 v3／v2／v1 配對格式 | [格式契約](docs/format.zh-TW.md) | | 生成可匯出至 Obsidian 的 Page | [完整技能與工具](skills/gpt-pages-obsidian-visualizations/SKILL.md) | | 核對原生圖與 Markdown 匯出的實測範圍 | [相容性紀錄](docs/compatibility.zh-TW.md) · [往返驗證摘要](docs/pages-roundtrip.zh-TW.md) | | 試讀通用、自行編寫的資料 | [靜態範例](examples/static.zh-TW.md) · [互動範例](examples/interactive.zh-TW.md) | | 準備圖片、跨 Page 連結與公式 | [可攜圖片](docs/images.zh-TW.md) · [跨 Page 連結](skills/gpt-pages-obsidian-visualizations/references/page-links.md) · [公式範例](skills/gpt-pages-obsidian-visualizations/assets/math-example.md) | ## 社群與回饋（Community and feedback） 歡迎在 [Obsidian 英文論壇展示主題](https://forum.obsidian.md/t/gpt-pages-importer-bring-pages-charts-and-interactive-html-into-obsidian-feedback-welcome/119527/3) 分享使用經驗，尤其是技能設定、首次匯入、圖片重匯與資料夾信任流程。簡體中文介紹文也已提交中文論壇，目前等待版主審核。 可重現的問題請至 [GitHub Issues](https://github.com/DLeungDL/obsidian-gpt-pages-importer/issues)，附上作業系統、Obsidian／外掛／renderer 版本、重現步驟與已去除隱私的小型範例。請勿在公開回報中附上私人 Page 或個人資料。 ## 開發與驗證（Development） ```sh npm run typecheck # TypeScript npm run build # 打包與載入檢查 npm test # Vitest 回歸測試 npm run check # 公開資料檢查 + 建置 + 測試 ``` 技能的 Python 驗證器另有標準函式庫測試： ```sh python -B -m unittest discover -s tests -p 'test_skill_export.py' -v ``` 轉換邏輯位於 [src/convert.ts](src/convert.ts)，匯入與衝突保護位於 [src/importer.ts](src/importer.ts)，自動清理位於 [src/cleanup.ts](src/cleanup.ts)。公開測試只使用虛構識別碼；私人 Page、原始匯出與截圖保留在 Git 外。
常見問題（FAQ） ### 為什麼只有原生圖片參照，沒有可攜的互動圖？ `visualize:` 參照本身不包含完整 HTML。請使用[生成技能](skills/gpt-pages-obsidian-visualizations/SKILL.md)，在 Page 頁尾加入與原生圖配對的完整來源，再匯出 Markdown。 ### 可以一次處理多份文件嗎？ 可以把多個 Markdown 放進監看資料夾或其子資料夾，由自動清理處理；手動匯入視窗每次選取一個檔案。 ### 會自動連線 Pages 下載或同步嗎？ 匯入與清理都使用你提供的 Markdown，不連線 Pages 下載附件，也不提供雲端或雙向同步。
## 支持開發（Support development）

喜歡 GPT Pages Importer 嗎？
請我喝杯咖啡，支持外掛維護、相容性改善、文件與範例。

請我喝杯咖啡（Buy Me a Coffee）

外掛維持免費與開源，贊助完全自願。謝謝你的支持！

## 授權（License） 本專案採 [MIT 授權](LICENSE)，包含外掛原始碼、文件與附帶的 Page 生成技能。打包依賴保留各自授權，完整聲明（third-party notices）隨發行檔提供，並嵌入 `main.js`。