Notation
Kristian Gaylord · 程式設計 · AI 學習
Notation 是免費的開源命令列工具，能把一整個資料夾的 Markdown 檔發布到 Notion。你在儲存庫裡寫文件，執行一個指令，Notion 就用搜尋與 AI 功能把內容呈現給讀者。
關於 Notation
About
什麼是 Notation
Notation 是一支終端機小工具，把裝滿 Markdown 檔的目錄整批寫進 Notion 頁面。專案以 Rust 撰寫，採 GPL-3.0 授權。只要下 notation ship --src，它就會掃過文件資料夾，在 Notion 裡重建整棵頁面樹。
背後的理由很直接：文件本來就屬於它所描述的程式碼，這就是文件即程式碼的做法。你在同一個 pull request 裡改 .md 檔，審查的人看得到差異，CI 也能順便執行發布。合併之後，沒有人需要再登入另一個服務。
有兩個限制決定它怎麼用。Notion 是唯一的目的地，所以發布目標永遠是你自己的頁面。同步方向只有一條，從 Markdown 進 Notion；儲存庫始終是唯一來源，在 Notion 裡打的字不會回流。
開始使用
- 用專案頁面上的 shell 腳本安裝。它會把執行檔放進
~/.notation，並在旁邊產生一份初始設定檔。 - 在 Notion 建立一個用來存放文件的頁面，名稱要能讓你在設定檔裡一字不差地重打一次。
- 到「設定與成員」建立內部整合，複製它的密鑰。回到父頁面，在「連接」加入這個整合，讓它有寫入權限。
- 打開
~/.notation/Notation.toml，填入兩個值：整合的secret與parent_page的標題。 - 在儲存庫執行
notation ship --src /你的/docs/路徑。到 Notion 確認結果，要對外就分享頁面，或用自訂網域指向它。
產品資訊
快速了解 Notation 的定價、支援平台與效能。
適合對象
這項工具最適合的使用者、任務與情境。
使用者
- 後端與平台工程師：文件就放在程式碼旁邊，同一個分支能同時改掉 API 端點和解釋它的那一頁。第一次發布前，你需要一個 Notion 工作區和一組整合密鑰。
- 沒有文件網站的小型產品團隊：一個 `docs/` 資料夾加一個指令，就有一套可讀、可搜尋的知識庫。不必架 build pipeline，不必付主機費，也不用學 React。
- 客服、業務與產品人員：他們在 Notion 裡讀結果，而多數團隊本來就天天開著 Notion。搜尋、留言和 AI 功能都現成，完全不用碰 Git。
任務
- 發布 API 參考文件：把端點說明留在儲存庫，每次上版後推到共用頁面，讀者看到的版本就等於實際出貨的版本。
- 更新新手導引：改一個設定步驟，就是在 Markdown 改一行，再跑一次同樣的指令。
- 把內部 runbook 變成 wiki：一層層的事件筆記資料夾，會變成一層層的 Notion 子頁面，而且全部都能搜尋。
情境
- 你已經在付 Notion，不想再買一套文件服務。Notation 只補上發布這一步，其他都不加。
- 文件之所以落後，是因為更新要特地開另一個工具。把來源搬回儲存庫，這段路程就消失了。
- 你希望文件跟程式碼一樣被審查。原始檔是版本控制下的純文字，原本的 pull request 流程自然涵蓋它。
主要功能
一個指令發布整個資料夾
notation ship --src 會走過來源目錄，把每個檔案寫進設定好的 Notion 頁面。沒有建置步驟，也沒有產生的網站要部署，從合併到上線只隔一個指令。
資料夾結構就是頁面結構
目錄變成子頁面，子目錄變成第二層子頁面，你在編輯器看到的樹狀結構，就是讀者在 Notion 看到的樣子。改資料夾名稱，對應頁面會在下次發布時跟著改名。
用 intro.md 寫父頁面
放在文件根目錄的 intro.md，內容會直接寫在父頁面上，不另外建立子頁面。這樣一個章節就有真正的首頁，有文字、有連結、有脈絡，而不是一個空容器加一串子頁面。
每頁自訂標題與圖示
Markdown 檔開頭可以用 --title 和 --emoji 兩個旗標，指定 Notion 頁面的名稱與圖示。setup.md 可以顯示成「Getting Started」加一個火箭，檔名維持機器友善，發布出去的標題仍然好讀。
內部 wiki 或公開網站
同一個發布目標，可以只留在自己的工作區內部，也可以分享成公開頁面。想要自訂網域，官方文件建議用 Super 當前端，notation.so 本身就是這樣跑的。
免費沿用 Notion 的搜尋、AI 與排版
內容進到 Notion 之後，搜尋索引、AI 問答、目錄和區塊排版全都現成。大規模文件搜尋本來就是難題，這裡直接交給別人處理。
優缺點
優點
- 免費且開源，採 GPL-3.0，沒有人數、方案或頁數上限要盯。
- 文件留在儲存庫裡，程式碼審查、分支與 CI 都能直接套用，不必額外設定。
- 安裝很短：裝好執行檔、建一個 Notion 整合、填兩個值。
- 讀者在 Notion 工作，搜尋、留言與 AI 回答就跟著團隊已經開著的那個工具一起來。
- 產出的頁面看起來像在 Notion 手做的，非技術讀者看不出它是從 Markdown 生成的。
缺點
- 同步只有單向。在 Notion 裡改的內容，下次發布就被覆蓋，所以儲存庫必須是唯一動筆的地方。
- 圖片需要公開網址，本機檔案不會上傳。你得把圖檔放在別處，再貼上連結。
- 每個人都要有 Notion 帳號、一個宿主頁面和一組內部整合密鑰，第一次跑成功之前有三個地方可能出錯。
- 專案規模小，最後一次提交是 2024 年 8 月。Notion API 一旦出現破壞性變更，就得有人修執行檔，而安裝腳本不支援 Windows。
常見問題
用來把 Markdown 轉成 Notion 頁面。你把 .md 檔留在程式碼儲存庫，執行 notation ship，它們就會以頁面樹的形式出現在你指定的 Notion 頁面裡。
相關內容
探索與 Notation 相關的工具、技能與文章。
Notation 替代方案
Base Code
Base44 (Wix) · 程式設計 · 生產力Base Code 是 Base44 推出的共享雲端開發環境。團隊在對話中描述對既有 GitHub 儲存庫的修改，看著預覽確認結果，再以 Pull Request 交回工程團隊。
Google EmbeddingGemma 2
Google DeepMind · 寫作 · 圖片 · 程式設計Google EmbeddingGemma 2 是 7.4 億參數的開源模型，能把文字、程式碼、圖片、音訊與影片畫面轉成同一個 768 維空間裡的向量，在手機與筆電上就能執行。
GitGlow
GitGlow · 程式設計 · 生產力GitGlow 是桌面版 Git 用戶端，把你自己的程式碼與 AI 代理程式的變更集中在同一份審查裡，讓你在交付前看清楚機器上究竟要送出什麼。