先用一份副本確認 README 的閱讀順序
送出 README 前,先把完整原稿複製到預覽區,從標題層級、段落、清單、連結到程式片段依序閱讀,並保留未改動的來源檔。預覽可以指出目前文字經工具解析後的樣子,卻不能保證 GitHub、GitLab、套件平台或公司內部系統會產生完全相同的畫面。
例如你準備交付一個小型命令列工具,README 同時包含安裝條件、使用方式、參數說明與故障排除。原始文字看起來都有換行,貼到專案頁後卻可能出現「安裝」與「使用」同級、清單縮排斷掉、反引號少一個,或相對連結指向錯誤位置。最有效的檢查不是只看語法有沒有上色,而是讓第一次閱讀的人能沿著正確順序完成一次任務。
先另存一份待檢查版本,並記下目標平台與 README 所在目錄。相對連結是否正確,會受到檔案位置影響;同一段 ./docs/setup.md 放在根目錄與子目錄,實際目的地可能不同。預覽前就把這個條件寫清楚,才不會把「畫面像連結」誤認為「連結一定可用」。
在 Markdown 編輯器檢查容易破版的區塊
把副本貼入 Markdown 編輯器,先看輸入區與預覽區是否都包含完整內容,再逐段核對。現在的工具會在瀏覽器中解析文字並產生預覽,也能複製產生的 HTML;它不會開啟專案資料夾、修改本機 .md 檔、儲存原稿或把內容推送到遠端平台。
優先檢查幾種最常讓 README 失去結構的細節:
- 文件標題只擔任整份文件的入口,後面的安裝、使用與疑難排解維持一致層級。
- 無序或有序清單的子項縮排一致,清單前後保留足以分段的空行。
- 行內程式碼的反引號成對,較長的程式區塊有清楚的開始與結束。
- 連結文字說得出目的地,網址括號完整,圖片也有能辨識內容的替代文字。
- 粗體、刪除線、引用、工作清單與簡單表格沒有吞掉相鄰段落。
這個預覽器支援常見標題、強調、連結、圖片、清單、引用、程式片段與簡單表格,並會處理輸入中的 HTML;但它不是任何特定託管平台的官方渲染器。平台可能另外支援目錄、自動連結、警告區塊、數學式或自訂擴充,也可能對原始 HTML、相對網址和安全屬性採取不同規則。工具頁顯示正常,只代表目前支援範圍內的解析結果。
用實際任務而不是外觀完成走查
版面整齊之後,從讀者的任務重新走一次。先假設自己剛拿到專案,依 README 找出環境需求、安裝命令、最小可執行範例、預期輸出與發生錯誤時的下一步。任何必須靠作者記憶補上的條件,都應在送出前寫回文件。
測試連結時,不要只確認藍色文字出現。外部網址要在新的瀏覽器分頁實際開啟;相對連結則回到專案的目標分支,從 README 所在位置點擊。範例命令也應在乾淨或接近新使用者的環境執行,確認參數名稱、大小寫、檔案路徑與輸出仍相符。預覽器只處理文字,不會替你執行命令或驗證下載內容。
若 README 是多人編修,可以把送審前版本與最後版本分別貼入 文字差異比較。它能比較貼上的文字並標出行、單字或字元差異,適合查看某次修訂是否意外移除段落;它不會讀取 Git 歷史、理解 Markdown 結構,也不會自動判斷哪一版正確。機密設定、權杖與真實客戶資料不應為了比較而貼入一般工具頁。
送出前保留可回復版本並做平台驗收
完成修改後,把通過檢查的 Markdown 存回一個新版本,再用 字數統計 看段落、行數與閱讀時間是否出現不合理變化。字數突然大幅減少可能代表貼上或合併時漏段;數字相近則仍不能證明內容相同,最後還是要查看差異與實際畫面。
送到目標平台的預覽或草稿頁後,做一次獨立驗收:
- 從頁首掃到頁尾,確認標題沒有跳級且目錄順序符合操作流程。
- 點開內部文件、外部網站與圖片連結,特別檢查相對路徑和大小寫。
- 複製最小範例到測試環境,確認命令能執行且輸出與說明一致。
- 用窄視窗查看長網址、表格和程式碼,確定重要內容沒有難以閱讀。
- 搜尋
TODO、範例權杖、個人路徑與內部主機名稱,避免把暫存資訊送出。 - 保留送出前原稿與通過驗收的版本,讓後續修改能追查差異。
如果平台沒有草稿功能,可以先在測試專案或未公開分支確認,但仍要遵守團隊的權限與機密規範。複製 HTML 也不是等同於發布 Markdown;HTML 的樣式、安全過濾和資源路徑仍由接收系統決定。
常見問題
預覽正常,為什麼貼到 GitHub 後還是不一樣?
不同平台可能採用不同的 Markdown 擴充、HTML 過濾、樣式與相對路徑基準。以目標平台的實際預覽為最後判準,並逐項測試連結與程式範例。
Markdown 編輯器會直接儲存我的 README 嗎?
不會。它處理貼入瀏覽器的文字並顯示預覽,也能讓你複製產生的 HTML,但不會修改或儲存專案檔案。原稿、備份與版本紀錄仍要由你管理。
可以把複製出的 HTML 當成任何網站的完成頁面嗎?
不建議直接這樣判定。接收網站可能移除部分標籤、套用自己的樣式,或使用不同的連結基準;貼入正式系統前要在該系統的測試或預覽環境驗收。
差異比較顯示沒有變更,就代表連結都有效嗎?
不是。文字相同只能表示兩份貼上內容沒有被比較器辨識出的差異,無法證明外部頁面仍存在、相對路徑正確或命令可以執行。
README 很長,應該只看閱讀時間嗎?
閱讀時間只能當作篇幅提示。更重要的是讀者能否快速找到先決條件、最小範例、預期結果與故障排除;必要時拆到獨立文件,並確認所有導覽連結可用。