FOAM

自由版的ROAM： 個人知識庫的解決良方。同時兼顧發布與儲存、分散及結構、適合程式及知識發展。

背景及需求目標

Visual Studio Code (VSCode)如果要取代個人wiki、作為非線性知識連結的首選， 就必須仰賴Foam插件的安裝及使用。

• PKM系統之比較([[2023-01-12-PKM]]¹)

300 篇筆記在code系統變成一個星空出來

Foam簡介

• Foam致力於建立卡片盒筆記法²的數位版本³、以及付費個人筆記系統Roam⁴的開源版本。
  • 相對於付費軟體Roam、Foam 是免費的、開源的，並且具有極強的可擴展性以適合您的個人工作流程。 您擁有您使用 Foam 創建的信息，您可以自由地分享它，並與任何你想要的人合作。
• VS市集之說明：Foam for VSCode
• Foam官網：Foam：Foam is a personal knowledge management and sharing system inspired by Roam Research, built on Visual Studio Code and GitHub.

Foam的裝置與設定

自空白模板開始

• 在github中抄一份foam模板
  1. 登入github系統後、
  2. 至https://github.com/foambubble/foam-template頁面、按下”Use this template”，內設是開啟一個新的repository(repo)，這會讓github知道儲存的位置，但也可以不儲存，只檢查檔案，可以網頁板的Codespace來開啟(在選取必要的檔案即可)。以下以內設方式進行。
  3. 開創新的repo(假設名稱為foam1)後，在https://github.com/sinotec2/foam1畫面Code<>下拉選單中選取複製Clone之HTTPS(https://github.com/sinotec2/foam1.git)，
  4. 回到本地、啟動GitDesktop程式、在右上方Current repository選擇Add下拉選單中的Clone repository貼上前述HTTPS，按下Clone鍵，即會在本機上複製一份模板。
  5. 點選GitDesktop主畫面Open in Visual Studio Code開啟VSCode及模板內容
  6. 進入VSCode時系統會提示安裝Foam及其他插件(第一次)，一一安裝即可。（插件包括：Markdown All in One、Markdown Emoji、Paste Image (see also [[2023-01-10-PasteImage]])、Todo Tree (see also [[2023-01-13-todo_tree]])) 和 Spell Right 等）

測試

• 按下ctrl-shift-p出現執行對話框，選取Foam: Show Graph 即會出現目前系統內所有檔案的關聯圖。
  • 開啟中的檔案名稱(title、黑色)及標籤(藍色)會出現圖中，與其關聯的其他檔案則以黑線與藍線相連
  • 拖動檔案及標籤可以確認其關係，
  • 如要加入檔案，點選檔案及進入編輯，在頁首加入相同標籤即可關聯。如要實質關聯，則要在至少一個檔案內加入另一方的[[wikilink]]
• 按下alt-d會開啟一個以日期時間為檔名的空白日誌。在.vscode/settings.json檔案中可以設定檔名格式與位置。
• 在左側多了
  1. 標籤欄(TAG EXPLORES(…))，數字表示標籤個數
  2. 孤兒欄(ORPHANS(…))，各目錄下無關連檔案的個數與總數
  3. 保留席(PLACEHOLDERS(…))，空的wikilink需要進一步定義
  4. 匯集所有反向連結BACKLINKS(功能待開發)

在既有repo(假設名稱為FAQ)中導入foam

• 先為自己的VSCode安裝foam插件
• 同時開啟form1模板以及FAQ
• 檢視2個repo的差異，將FAQ沒有的目錄(如.foam)、沒有的檔案(如.vscode/foam.json)、複製或開創，以有的檔案(如前述.vscode/settings.json)則予以合併(聯集)
• 同樣進行前述測試

Foam問題與解決

與發佈系統的衝突

• 雙向連結([[...]]、wikilink)並不是每一個發布系統都能接受，因此發布前會需要轉譯。
  • 將wikilink轉譯成定義(reference definitions，[.]: <http...> "...")
• 官網介紹了自2個方式來執行轉譯
  • 啟動VSCode的轉譯功能：ctrl,，Foam> Edit: Link Reference definitions (Modified in Workspace)，有3個選項(是否含附加檔名、及關閉)，會針對工作區(或所有個人檔案都進行轉譯)
  • 手動在對話框(ctrl-shift-p)執行Foam: Run Janitor來批次執行轉譯。
• 轉譯結果會有問題
  • 定義中的網址只有檔案名稱、如以TeXt進行發布，所有檔名的年月日將轉成gh_page的目錄，因此連結無法成功。
  • 如以絕對路徑取代wikilinks，在VScode將不會有hover預覽。

折衷方案

• 將文中的wikilinks保持不動，雖然會在發布網站上顯示出奇怪的雙方括弧，但可以保持在VScode上的展現能力。
• 在wikilinks後加註腳(footnote、peek note、參見[[2023-01-10-FootNoter]]⁵)，不致造成本文太大干擾
• 在註腳中顯示reference definitions，給予絕對路徑，使用者如果想去造訪再點入選即可。
• 發布時逐一執行以下janitor3.py即可。

janitor3.py

IO

• 引數：需要發布的md檔，檔名前綴為年月日
• 讀取：wikilink連結到的檔名，同一目錄、檔名前綴為年月日
• 輸出：覆蓋同一檔名

注意事項

1. VSCode環境與shell不見得看得懂中文，需特別指定編碼方式
2. 預先篩除沒有wikilink的情況
3. 因應原文件內容之檢視
   1. 已有註腳([^ ])，要注意從既有最高編號再往上編碼。
   2. 如有半個[[ (janitor3.py itself))
   3. 如有bash之 if [[...]]
4. 程式目前還沒有設計成可以連到目錄以外的檔案，但程式會報錯不執行轉譯。還是需手動一一指定。
5. 同一行有多項wikilink的情況，在程式中可以通案處理。

程式碼

• 使用.startswith找到文字中含有特定字串的位置：

      begs=[j for j in range(len(ll)) if ll.startswith('[[', j)]
      ends=[j for j in range(len(ll)) if ll.startswith(']]', j)]

心得評論

其他人的意見

• VSCode+FOAM還不是一個普遍的方案，從2020公開迄今約有86K下載安裝，相關介紹如
  • VS Code 中的双链笔记：Foam 使用体验分享、少數派终古暮鸦2022 年 01 月 14 日

    與 Roam Research 和 Obsidian 等專業筆記軟體相比，Foam 或許沒有獨特優勢，甚至在某些方面支援並不完善。但好在作為一個開源專案，它能夠深植良好的社群環境，吸收使用者的建議與反饋，讓每個人都成為專案的貢獻者。

  • Foam vs Roam Research, stackshare.io，後者似乎有較多的跟隨者與參與者
  • Foam — A Roam Research alternative with VSCode, Markdown and GitHub@reddit.com這項3年前開始的投票，似乎大多數人(96%)會選擇前者。
  • Foam-vscode笔记入门/教程by jackiexiao@知乎將Foam常用指令列表比較
  • Foam – A Roam Research alternative with VSCode, Markdown and GitHub (github.com/foambubble) @Hacker News這篇有從不同使用者角度的討論。雖然有點古老。

使用時機

• 同時寫程式、寫程式說明…VSCode+Foam是個非常理想的方案，值得推薦。
  • 動態關聯圖在系統架構還不是很清楚、tags下的文件還不是很多的時候，有非常大的貢獻
  • wikilink的定義對寫作邏輯的建立也非常有貢獻
• 零散文件之關聯：透過ORPHANS解決過程，找到散佚文件的應用，不致散失重要資訊、將其活化應用(甚至更新)，這也是知識庫的用意之一。
• 自由軟體的同步更新
  • VSCode的功能持續更新
  • 其他插件的貢獻
• 有些人命名為非線性思考、有些人認為是網絡思考，不論Foam/Roam等這類的PKM實際作業時，每次需要更新的範圍不會是一個小元件、單一檔案，而是所有關連到的前後文件，這是很實質的改變。

TODO

• 週期匯總日報
• 安裝TODOS TREE