開發者工具集
返回 網站動態
DevTool 團隊

README.md 線上預覽：提交 GitHub 前檢查 GFM 排版

提交 GitHub 前如何線上預覽 README.md？用這份清單檢查標題結構、GFM 表格、工作清單、程式碼區塊、相對連結、圖片、Mermaid 與行動版排版。

README 預覽的目標是減少提交後的意外

README.md 往往是專案的第一份使用說明。使用者會從這裡判斷專案是什麼、如何安裝、怎樣執行、遇到問題去哪裡找。原始碼中的一個小錯誤，例如未閉合的程式碼圍欄或失效的相對圖片，會直接影響第一印象和操作成功率。

提交前用Markdown 線上閱讀器開啟 README，可以並排檢查原始碼和渲染結果。它適合發現通用 Markdown 與 GFM 排版問題；儲存庫路徑、徽章服務和 GitHub 專屬行為則需要在目標平台再確認一次。

一份可快速瀏覽的 README 應該怎樣組織

沒有適合所有專案的固定範本，但多數開發者工具可按下面的閱讀順序組織：

  1. 專案名稱和一句明確說明；
  2. 可選的狀態徽章和真實產品截圖；
  3. 安裝需求與最短安裝指令；
  4. 一個可以複製執行的最小範例；
  5. 設定、常見用法與限制；
  6. 測試、貢獻、授權和支援管道。

標題層級應形成連續結構。README 通常已有一個 H1，後續使用 H2 和 H3，不要為了視覺大小直接從 H2 跳到 H4。線上預覽時開啟目錄，可以快速發現層級是否混亂或標題是否過長。

提交前的 GFM 檢查清單

表格

檢查表頭分隔列、直線數量和窄螢幕表現。內容較長時，清單通常比六七欄的大表格更易讀。表格儲存格內換行和複雜 HTML 的結果可能因平台不同而變化。

工作清單

使用 - [ ] 與 - [x]，並確保前面有空格。工作清單適合路線圖和完成狀態，但不要把關鍵安裝步驟做成看似可點選、實際不可操作的核取方塊。

程式碼區塊

每個圍欄程式碼區塊應閉合並標示正確語言。指令範例不要包含 shell 提示符，否則使用者複製時還要刪除。分別標明 Bash、PowerShell 或其他平台差異，避免把多套指令混在同一區塊。

npm install
npm run dev

連結與圖片

相對連結的解析位置取決於 README 所在目錄和查看頁面。./docs/setup.md、../assets/demo.png 在本機預覽器中缺少儲存庫基準位址時可能無法顯示，但在 GitHub 上有效；反過來，依賴本機絕對路徑的連結在提交後一定失效。

提交前可逐項確認：

  • 檔名大小寫與儲存庫完全一致；
  • 圖片使用儲存庫相對路徑或穩定的 HTTPS 位址；
  • 標題錨點在改名後同步更新；
  • 外部連結沒有指向登入後才可見的頁面；
  • 圖片有簡短、具體的替代文字。

Mermaid、數學公式和 HTML 的相容性

GitHub 支援多種 GFM 語法，也支援特定 Mermaid 程式碼區塊，但 npm、PyPI、公司內部文件網站或其他 Git 託管平台的能力可能不同。KaTeX 數學公式、GitHub Alerts、註腳和 emoji 同樣需要按發布目標驗證。

原始 HTML 的差異尤其明顯。出於安全原因，預覽器和平台通常會移除腳本、事件屬性或危險標籤。本站閱讀器預設不解析內嵌 HTML，可避免預覽不可信 README 時執行內容，但這也表示依賴 <details> 或複雜 HTML 表格的頁面不會完全複製 GitHub。

更完整的語法界線可參考Markdown 線上預覽相容性指南。

用真實讀者任務檢查內容

排版沒有報錯，不代表 README 已經完成。按第一次接觸專案的讀者視角完成一次任務：

  1. 只閱讀首屏，能否說清專案用途和適用對象？
  2. 從空目錄開始，安裝指令是否包含必要前提？
  3. 複製最小範例，是否能得到文件描述的結果？
  4. 設定項是否說明預設值、是否必填和敏感資訊處理方式？
  5. 失敗時是否能找到疑難排解、issue 範本或支援入口？

這些驗證不能由 Markdown 渲染器取代，但線上預覽可以讓說明結構和指令邊界更容易檢查。

在桌面和手機寬度下各看一次

README 的訪客不一定使用桌面電腦。切換窄視窗後重點觀察：

  • 過長的專案名、URL 和無法換行的指令；
  • 表格是否造成整頁水平捲動；
  • 大圖是否有合理尺寸；
  • 徽章過多時是否擠占主要資訊；
  • 目錄和長清單是否仍能快速瀏覽。

不要為了讓桌面版整齊而使用大量空格手動對齊。Markdown 的價值在於結構可以跨裝置重新排版。

隱私與外部資源

本站閱讀器選擇的本機 README 和貼上文字在瀏覽器內處理；主動載入 raw URL 時會請求對應遠端主機。頁面中的外部圖片或連結也可能在最終平台產生第三方請求，因此範例中不要嵌入帶使用者識別的追蹤位址。

分享連結雖然把正文放在 URL fragment 中、不把 fragment 傳送給本站伺服器，但完整連結仍可能保存在歷史記錄或被接收者轉傳。含私有儲存庫資訊、金鑰和內部網域的 README 不應透過分享連結傳播。

建議的提交順序

  1. 在本機完成內容和指令驗證。
  2. 用線上閱讀器檢查通用 GFM 排版、目錄、程式碼區塊和窄螢幕表現。
  3. 執行儲存庫已有的 Markdown lint、連結檢查或文件建置。
  4. 推送分支後，在 GitHub 的最終渲染頁面核對相對資源和平台擴充。
  5. 讓一位不了解專案的人依 README 完成最小任務，記錄真正卡住的位置。

還沒有合適的開啟方式時，可先閱讀Windows、macOS 和手機開啟 .md 檔案的方法。準備好檔案後，直接線上預覽 README.md。