Skip to content

Markdown 內容規範

以下 Markdown 內容規範會在驗證器中被強制執行:

  1. 標題: 使用適當的標題階層(H1、H2、H3 等)來組織內容。並依照階層順序使用。
  2. 清單: 使用項目符號或編號清單。確保適當的縮排與間距。
  3. 程式碼區塊: 使用 fenced 程式碼區塊來放置程式碼範例。為語法高亮指定語言。
  4. 連結: 使用正確的 Markdown 語法來建立連結。確保連結有效且可存取。
  5. 圖片: 使用正確的 Markdown 圖片語法。為無障礙性加入替代文字(alt text)。
  6. 表格: 使用 Markdown 表格呈現表格式資料。確保格式與對齊正確。
  7. 行長: 為可讀性將行長限制為 400 字元。
  8. 空白: 使用適當的空白以分隔章節並提升可讀性。
  9. Front Matter: 在檔案開頭包含 YAML front matter,並附上必要的 metadata 欄位。

格式與結構

請依下列指引格式化與結構化 Markdown 內容:

  • 標題: 使用 # 作為 H1,使用 ## 作為 H2,使用 ### 作為 H3。確保標題以階層方式使用。若內容包含 H4,建議重新調整結構;若包含 H5,強烈建議重構。
  • 粗體(**):不要濫用粗體,僅在真正需要強調、極為重要的內容時才使用。過度使用會降低重點效果,影響可讀性。
  • 清單: 使用 - 作為項目符號和 1. 作為編號清單。巢狀清單以兩個空格縮排。
  • 程式碼區塊: 使用三個反引號(```)來建立 fenced 程式碼區塊。於開頭的反引號後指定語言以啟用語法高亮 (e.g., ```javascript).
  • 連結: 使用 [link text](URL) 建立連結。確保連結文字具描述性且 URL 有效。
  • 圖片: 使用 ![alt text](image URL)。在 alt text 中加入簡短描述。
  • 表格: 使用 | 來建立表格。確保欄位對齊並包含標頭。
  • 行長: 在 80 個字元處斷行以提升可讀性。對長段落使用軟斷行。
  • 空白: 使用空行來分隔章節並提升可讀性。避免過多空白。

驗證需求

確保符合下列驗證需求:

  • 內容規則: 確保內容符合上述的 Markdown 內容規範。
  • 格式: 確保內容依指引進行正確格式化與結構化。
  • 驗證: 執行驗證工具以檢查是否符合規範與指引。