Mote — Markdown in, URL out
Mote 將 Markdown 發布為不可變、不可枚舉、瀏覽器可讀的線上頁面，並回傳一個 URL。本 Skill 僅指導何時以及如何使用 Mote；發布協定由 CLI / MCP 實作，不要自己實作上傳邏輯。
何時使用
滿足以下任一意圖時使用 Mote：
- 「把這份 Markdown / 報告 / 文件分享出去」「發成網頁 / 連結」
- 明確要求把設計文件、調研材料、會議記錄或 README 變成線上連結
- 要求把你剛生成的報告/分析結果發布為網頁
僅閱讀、編輯 Markdown 或在本地瀏覽器預覽時，不發布到 Mote。
不要使用：
- 內容包含密碼、API Key、私鑰等憑證，或企業機密——Mote 的 URL 即存取憑證，知道連結即可閱讀，目前不提供使用者側刪除入口
- 需要修改已發布內容——Mote 文件不可變；改內容必須重新發布得到新 URL
如何發布
先檢查是否參照本地圖片，再按已設定的工具選擇路徑。尊重使用者指定的實例；已有自託管設定時，不強制切換到公用實例 https://mote.pub。
路徑 A：MCP 工具（如果 mote MCP server 已連線）
- 內容在對話中且沒有本地圖片 → 呼叫
publish_markdown，傳markdown（可選name，如report.md）。本地和遠端的這個工具都不收集本地圖片，只保留遠端圖片 URL。 - 本地 Markdown 檔案 → 僅本地 stdio 提供
publish_markdown_file，傳path（本地圖片自動上傳、按內容去重）；遠端只有publish_markdown，需要本地檔案/圖片時使用已設定的 CLI，不把路徑傳給遠端工具。
路徑 B：CLI（已安裝且已設定鑑權時可用）
- 已有檔案直接發布原檔案。對話內容沒有本地圖片時，可寫入暫存檔案；有本地圖片時，將 Markdown 與所需圖片放入保持相對路徑關係的暫存目錄，再透過 CLI 或本地
publish_markdown_file發布。圖片相對於 Markdown 檔案所在目錄解析，不是相對於終端工作目錄；不要只把 Markdown 移到/tmp。 - 執行：
mote <file.md> --json
- 解析 stdout 的 JSON：
{ "id": "...", "url": "..." }
CLI 會自動處理 Markdown 和支援 HTML 中的本地圖片參照、路徑驗證、上傳和內容去重；遠端圖片保留原 URL，不會下載打包。只有圖片會隨文件上傳，指向其他本地 Markdown 檔案的連結不會自動發布目標檔案。
內容相容性
- 支援常用 Markdown、表格、任務列表、腳註、GitHub 風格 Alerts，以及指定語言的程式碼高亮。
- 數學公式支援 TeX 子集；
mermaid程式碼區塊支援六類靜態圖表子集，每篇最多嘗試渲染四個圖表。無效、不支援或超出預算的內容可能顯示為原始碼，發布成功不代表所有擴充語法均已渲染。 - HTML 僅允許安全子集，不執行腳本、MDX 或互動嵌入。不支援上傳或直接嵌入原始 SVG；Mote 生成的圖表 SVG 經獨立清理，可以顯示。
- 發布複雜公式或圖表後，檢查實際頁面的公式、連線、標籤和圖片；未經檢查，不聲明渲染效果已驗證。
需要詳細語法或限制時，查看相容性說明及線上案例。自託管實例的支援範圍取決於部署版本。
如何處理回傳的 URL
- 原樣把 URL 回傳給使用者，不要截斷、不要改寫；
- 一句話說明即可，例如「已發布：」；
- 頁面設定了禁止搜尋引擎索引的指令，這不是存取控制或絕對不被收錄的保證；可存取性取決於實例和儲存持續執行；
- 如果使用者後續要求「更新這個頁面」：說明已儲存的 Markdown 和已上傳資產不可變，重新發布會得到新 URL；Viewer 更新可能改變呈現效果，遠端圖片依賴來源站點。
限制（發布前自檢）
- Markdown ≤ 2 MiB；單張圖片 ≤ 10 MiB；上傳資產 ≤ 50；整個包 ≤ 20 MiB。1 MiB = 1,048,576 位元組，CLI 按內容去重後計數，遠端圖片不計入
- 圖片格式：png / jpeg / webp / gif / avif（不支援 SVG）
- 超出限制時如實告訴使用者哪一項超限，不要自行刪減內容
常見錯誤
- 登入失效：引導使用者針對同一實例完成互動登入；使用者已明確要求協助登入時，按授權範圍繼續。不因發布失敗擅自發起瀏覽器登入、不讀取其他用戶端的憑證、不切換回舊 token。具體步驟見鑑權說明；
no publish token configured：確認實例的鑑權模式。靜態模式需要實例管理員提供 token；Access 實例需要 OAuth 登入或顯式機器模式，不能把 Cloudflare 管理 API token 當發布金鑰；不自行生成憑證；- 機器模式：需要顯式
MOTE_AUTH_MODE=service及目標匹配的MOTE_SERVICE_API_URL、MOTE_SERVICE_CLIENT_ID、MOTE_SERVICE_CLIENT_SECRET。缺失或無效時停止，不用使用者登入態替代； - 逾時、5xx 或結果未知：不自動重試發布，可能已經生成不可變文件；先核對結果，再由使用者決定是否重新發布；
asset not found: <path>：Markdown 參照的本地圖片不存在，提醒使用者檢查相對路徑；unsupported image type：參照了 SVG 等不支援格式，建議使用者轉換為 png/webp 後重試。