使用 Markdown 外掛程式

概觀

JSDoc 包含一個 Markdown 外掛程式，可自動將 Markdown 格式的文字轉換為 HTML。您可以在任何 JSDoc 範本中使用此外掛程式。在 JSDoc 3.2.2 及更新版本中，Markdown 外掛程式使用 marked Markdown 剖析器。

注意：當您啟用 Markdown 外掛程式時，請務必在 JSDoc 註解的每一行開頭加上星號。如果您省略開頭的星號，JSDoc 的剖析器可能會移除用於 Markdown 格式化的星號。

預設情況下，JSDoc 會在以下 JSDoc 標籤中尋找 Markdown 格式的文字

• @author
• @classdesc
• @description（包括 JSDoc 註解開頭未標籤的說明）
• @param
• @property
• @returns
• @see
• @throws

啟用 Markdown 外掛程式

若要啟用 Markdown 外掛程式，請將字串 plugins/markdown 加入 JSDoc 設定檔 中 plugins 陣列

{
    "plugins": ["plugins/markdown"]
}

在其他 JSDoc 標籤中轉換 Markdown

預設情況下，Markdown 外掛程式只會處理 特定 JSDoc 標籤 的 Markdown 文字。您可以透過在 JSDoc 設定檔中加入 markdown.tags 屬性，來處理其他標籤中的 Markdown 文字。markdown.tags 屬性包含一個陣列，其中包含可以包含 Markdown 文字的其他文件屬性。（在大部分情況下，文件屬性的名稱與標籤名稱相同。不過，有些標籤儲存方式不同；例如，@param 標籤儲存在文件屬性的 params 屬性中。如果您不確定標籤的文字如何儲存在文件中，請執行 JSDoc 並加上 -X/--explain 標籤，這會將每個文件列印到主控台。）

例如，如果 foo 和 bar 標籤接受儲存在文件屬性 foo 和 bar 中的值，您可以透過在 JSDoc 設定檔中加入以下設定，來啟用這些標籤的 Markdown 處理

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["foo", "bar"]
    }
}

從 Markdown 處理中排除預設標籤

若要避免 Markdown 外掛程式處理任何 預設 JSDoc 標籤，請將 markdown.excludeTags 屬性新增至您的 JSDoc 組態檔。markdown.excludeTags 屬性包含一個預設標籤陣列，不應針對 Markdown 文字進行處理。

例如，若要將 author 標籤排除在 Markdown 處理之外

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "excludeTags": ["author"]
    }
}

在斷行處強制換行文字

預設情況下，Markdown 外掛程式並不會在斷行處強制換行文字。這是因為 JSDoc 註解跨多行換行是很常見的。如果您偏好於在斷行處強制換行文字，請將 JSDoc 組態檔的 markdown.hardwrap 屬性設定為 true。此屬性適用於 JSDoc 3.4.0 及後續版本。

將 ID 屬性新增至標題

預設情況下，Markdown 外掛程式並不會為每個 HTML 標題新增 id 屬性。若要根據標題文字自動新增 id 屬性，請將 JSDoc 組態檔的 markdown.idInHeadings 屬性設定為 true。此屬性適用於 JSDoc 3.4.0 及後續版本。