HackMD

Markdown 協作筆記

jackycute @ 2016 MOPCON

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

吳承翰 Max Wu

北科大 資訊工程所

我喜歡好的產品，也開發好的產品；
我寫的不是程式，是理想。

HackMD

Realtime collaborative markdown notes on all platforms

工程師看到的時候想：

  • Realtime；那就是很快就可以看到結果的意思
  • Collaborative；就是可以跟別人一起同時工作
  • Markdown；就是 GitHub 還有 堆疊溢出 在用的語法嘛
  • Notes；喔 Evernote 還是 Quip 都用過啦
  • Platforms；阿不就跨平台好棒棒

一般人看到的時候想：

  • Realtime；即時？阿是有多即時？FB 那樣嗎？
  • Collaborative；協作？Google Doc 我聽過
  • Markdown；你給我解釋解釋，解釋解釋
  • Notes；我們公司都用 Word 作筆記傳 FTP
  • Platforms；不懂你的意思，可以說清楚一點嗎？

Hack + MD

Hack

用聰明的方法來完成事情

Markdown

輕量的視覺化標記語言

「蛤？」

文字就可以排版的語法

感謝 @clkao 貢獻此麻瓜咒語

HackMD

  • 靈感來自 Hackpad
  • 更注重速度與靈活度
  • 跨平台的筆記服務

用途

  • 製作筆記
  • 撰寫文件
  • 快速簡報

功能

  • 自動上傳圖片
  • 支援嵌入影片
  • 支援數學公式
  • 支援各式圖表
  • 自動修訂紀錄
  • 自動作者標記

採用

  • PyCon TW 2016
  • g0v
  • CTF write-ups
  • Debater
  • 成大 進階電腦系統理論與實作 (Fall 2016)

現況

  • 2015 年 3 月開始上線服務
  • 累計超過 5.2 萬份筆記
  • 每月超過 3.4 萬的活躍使用者
  • 會員超過 7,500 名
  • 使用者來自 台灣、日本、美國、歐洲、南美洲
  • 支援超過 15 種介面語言

開源

  • 被星星超過 1,000 次
  • 擁有超過 24 名貢獻者
  • 被 Fork 超過 130 次

架構

  • 前端使用 jQuery
  • 後端使用 Node.js
  • 資料庫使用 PostgreSQL

一個人怎麼實踐理想？

「組合肉」

起源

資訊安全 期末專案

好奇即時協作的原理與其中的安全問題

因為我很懶所以愛上優雅的 Markdown

做法：

  1. 上網餵狗搜尋 Collaborate Editor
  2. 找最容易看得懂的範例開始改起
  3. 找可以用的 Open Source 套件加料
  4. 研究原始碼填補接縫
  5. 測試功能正常，美化外皮

結論：兩天完成的夜市牛排

  • 可以多使用者同時協作文字
  • 實作對稱式加解密 (AES)
  • 其實就是實踐 MVP (最小可行產品) 的過程

劇終

  • 這個專案拿到 99 分
  • 做完就去放寒假了 XD
  • 沒有人愛你
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →

Re: 從零開始的協作筆記

  • 既然用了 Markdown 就要渲染成 HTML 啊！
  • 既然都是網頁了不如支援一下 RWD (響應式網頁設計)
  • 先來場大亂鬥看看會發生甚麼事情？！

選擇 Markdown renderer

  • chjj / marked 10766 298
  • jonschlinkert / remarkable 2881 53
  • markdown-it / markdown-it 2656 2
  • wooorm / remark 715 5

chjj / marked

  • 輕量、效能最好
  • 沒有遵循任何標準
  • 自訂語法較困難

markdown-it / markdown-it

  • 效能佳
  • 遵循 CommonMark
  • 容易自訂語法
  • 外掛多

jonschlinkert / remarkable
基本上已棄用，markdown-it 的前身

wooorm / remark

  • 效能好
  • 遵循 CommonMark
  • 有制定一套 AST (虛擬結構樹)
  • 外掛多
  • 明日之星
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →

CommonMark

因為 Markdown 是開放格式
所以各自制定的語法有非常多種

目前 CommonMark 為大多數人遵循的標準

跨平台介面設計

  • 使用 Bootstrap，內建 RWD
  • 無論整合什麼都要看起來像 Bootstrap
  • 盡量讓所有功能可用，不能用的直接藏起來

跨平台也能保持良好的使用者體驗

了解瀏覽器的設計，盡量保留原生功能

  • body scrolling 的時候工具列會縮小
  • 輸入的時候虛擬鍵盤會彈出來
  • #hash 是拿來定位 id anchor 的
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →

跨平台介面開發與除錯

  • 善用響應式設計模式預覽 (Safari)
  • 善用 Remote 除錯 (Chrome, Safari)
  • 實機測試最準確
  • 為不同螢幕裝置做更詳細的最佳化

使用者總能挑戰裝置的極限！

  • 這麼小的螢幕上還是要用 IDE！
  • 超小的元素還是被點到了！
  • 行動網路很慢，但是硬要用！
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →

社群推廣大亂鬥

  • 分享到 FB 的幾個較大的資訊相關社團
  • 自己分享到 Hacker News
  • 造成空前的流量，很多人一起測試輸入

大爆炸
Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

  • 有人嘗試輸入 40 萬字，造成 CPU 負載過重
  • 有人嘗試輸入 不安全的語法
  • 多人一起輸入會搶字

適當且無感的限制

  • 限制最大輸入字數，超過會提醒
  • 自動過濾所有渲染出來的 HTML

如何協作同步？

  • 輸入拼字也需要同步
  • 網路延遲造成同步錯亂

拼字問題

  • 輸入需要拼字的還有 日文、韓文 等
  • 拼字的時候瀏覽器有事件 (compositionStart 等)
  • 但是會因為裝置、瀏覽器而實作有所不同
  • 總之不要忽略拼字，ㄅㄆㄇㄈ也需要同步

Operational Transformation 操作轉換

無法避免因為網路延遲所導致的資料不同步

多人協作的時候需要將輸入的操作結構化
然後按照順序轉換成相對應的操作並同步

共有三種操作

  • Retain 多少字元不更動
  • Insert 插入字元
  • Delete 刪除字元

如何轉換？

以「PPAP」為例

PP→PPAP

sequenceDiagram
    Client A->>Server: O1: Insert[1, 'P', 1]
    Client B->>Server: O2: Insert[1, 'A', 1]
    Server-->>Client B: O1': Insert[1, 'P', 2]
    Server-->>Client A: O2': Insert[2, 'A', 1]

PAAP→PPAP

sequenceDiagram
    Client A->>Server: O1: Delete[1, 'A', 2]
    Client B->>Server: O2: Insert[1, 'P', 3]
    Server-->>Client B: O1': Delete[2, 'A', 2]
    Server-->>Client A: O2': Insert[1, 'P', 2]

資料儲存架構

  • 將具有即時性的資料暫存在記憶體
  • 變更資料的同時標記此筆資料變更
  • 使用非同步 Workers 掃描變更資料並存回資料庫

Worker 的工作流程

st=>start: 資料存取
e=>end: 刪除暫存
op1=>operation: 暫存資料至記憶體
cond1=>condition: 資料是否被變更？
cond2=>condition: 資料是否逾時未變更？
op2=>operation: 儲存變更資料回資料庫
st->op1->cond1
cond1(yes)->op2->e
cond1(no)->cond2->op1
cond2(yes)->e
cond2(no)->cond1->sub1

如何記錄修訂版本？

  • google-diff-match-patch
  • 只記錄 patch 減少重複內容

google-diff-match-patch

  • 基於 Myer's diff algorithm
  • 加上預處理 (加速)
  • 加上後處理 (減少多餘的結構)

diff 範例

  • old: 假的業障重, new: 假的暫時的
  • diff 得到：假的業障重暫時的
  • 轉成 GNU unified format patch 
    



    ​​​​@@ -1,5 +1,5 @@
​​​​ 假的
​​​​-業障重
​​​​+暫時的

只儲存 patch 減少資料量

  • 只有最新與最舊的版本會完整儲存
  • 當拿取中間版本時，由最靠近的完整版本 patch 回來
  • 從舊版本計算出較新版本 → patch
  • 從新版本計算到較舊版本 → inverse patch

如何整合套件

  • 要整合的無縫
  • 要能發揮它的力量
  • 了解它、修正它、Fork 它
  • 不吝給予回饋 (開 Issue、發 PR)

目前已整合的重要套件

  • CodeMirror
  • socket.io
  • OT
  • textcomplete
  • bootstrap
  • markdown-it
  • reveal.js
  • google-diff-match-patch

為何不重造輪子

  • 因為沒那麼多資源
  • 因為沒有那麼專業

為何重造輪子

  • 因為可以完全自訂
  • 因為可以知道細節

設計與核心思想

「懶」

懶得優雅

懶得簡潔

實踐方法

  • 只出現必要的元件
  • 注重微小的細節
  • 好的體驗是由無數個細節構成

自己吃吃看狗糧

  • 最好的電影是連導演都感動
  • 最棒的服務是連自己都驚嘆

社群是你最好的導師

  • 自己的痛點可能也是別人的痛點
  • 用 open source 實踐 MVP

別想單打獨鬥解決所有困難

  • 勇者，不要跟他拼拳，嘗試切他中路！
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
  • 嘗試創造不存在那些痛點的世界 (但是有 tradeoffs)
  • 想法 → 課程專案 → Issue DD → Community DD

樂於與社群互動

  • 關心使用者，提供管道並傾聽他們的聲音
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
  • 與敬佩的對手聯誼，市場夠大不要小氣
  • 研究 → 設計 → 實作 → 驗證 → 回饋

最好是免錢又大碗又好吃

  • 這是不可能的
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
  • 必須在設計、開發、營運之間嘗試平衡
  • 將所有功能都集合的不一定是好產品

感謝貢獻與推廣

@clkao @neil @BlueT @ETblue @EvanWu @yukai @PeterDaveHello @ttcat @BobbyTung @xnum @au @g0v and more…

感謝贊助

已收到超過 250 美元的捐贈！

搜尋並加入

Markdown 台灣

Q&A

⨯

HackMD
已列入
GitHub Integrations List

謝謝大家！

這份簡報使用 HackMD 製作
https://hackmd.io/p/Bk9X2eJT

Select a repo