Markdown プラグインの使用

概要

JSDoc には、Markdown フォーマットされたテキストを自動的に HTML に変換する Markdown プラグインが同梱されています。このプラグインは、すべての 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 プラグインは Markdown テキストの 特定の JSDoc タグ のみ処理します。JSDoc 設定ファイルに markdown.tags プロパティを追加することで、他のタグの Markdown テキストを処理できます。markdown.tags プロパティには、Markdown テキストを含めることができる追加の doclet プロパティの配列が含まれています。(ほとんどの場合、doclet プロパティの名前はタグ名と同じです。ただし、一部のタグは異なって格納されます。たとえば、@param タグは doclet の params プロパティに格納されます。タグのテキストが doclet にどのように格納されているかわからない場合は、各 doclet をコンソールに出力する -X/--explain タグを使用して JSDoc を実行します。)

たとえば、foo タグと bar タグの値が doclet の 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 以降で使用できます。