DOCSEARCHbyAlgolia
Submit Docs

jsdoc-to-markdown

repository·master·Indexed 22 days ago

https://github.com/jsdoc2md/jsdoc-to-markdown

A tool and library (version 9.1.3) that generates Markdown API documentation from JSDoc annotated source code. It provides a CLI (`jsdoc2md`) and a JavaScript API featuring methods like `.render()` for generating documentation, `.getTemplateData()` for processed JSON data, and `.getJsdocData()` for raw JSDoc engine output. It supports custom Handlebars templates, GFM configuration, and various output formats for parameters and indexes.

Tokens
2.5K
Snippets
6
Records
18
Agent score
82%

What's inside jsdoc-to-markdown

  2. Generate markdown documentation from JSDoc

    master

    To generate markdown API documentation, follow these three steps:

    1. Document your code: Use valid JSDoc comments in your source files.
    2. Run the CLI: Execute the jsdoc2md command followed by the path to your source file.
    3. Retrieve output: The tool will output formatted markdown containing function signatures, descriptions, and parameter tables.

    Example Workflow

    Source Code (example.js):

    /**
 * A quite wonderful function.
 * @param {object} - Privacy gown
 * @param {object} - Security
 * @returns {survival}
 */
function protection (cloak, dagger) {}

    Command:

    $ jsdoc2md example.js

    Markdown Output:

    ## protection(cloak, dagger) ⇒ <code>survival</code>
A quite wonderful function.

**Kind**: global function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | Privacy gown |
| dagger | <code>object</code> | Security     |

  5. Clear the jsdoc2md cache with .clear()

    master
    By default, the output of generation methods (render, getTemplateData, etc.) is stored in the system's temporary directory to speed up repeat invocations. If the input options or source code changes, fresh output is generated. Use .clear() to manually clear the cache if it is failing for some reason.

  6. Get raw JSDoc data with .getJsdocData()

    master

    The .getJsdocData([options]) method returns raw data directly from the underlying jsdoc3 engine. It returns a Promise<Array.<object>>.

    Options

    OptionTypeDescription
    no-cachebooleanIf true, disables caching. By default, results are cached to speed up repeat invocations with the same input.
    filesstring or Array<string>One or more filenames to process. Accepts globs (e.g. *.js).
    sourcestringA string containing source code to process.
    configurestringThe path to the JSDoc configuration file.

    Note: One of files, source, or configure must be supplied.

  8. Render markdown documentation with .render()

    master

    The .render([options]) method returns markdown documentation from JSDoc-annotated source code. It returns a Promise<string> which resolves to the rendered documentation.

    Options

    OptionTypeDescription
    dataArray.<object>Raw template data to use. Useful when you already have template data, obtained from .getTemplateData(). In the options, one of files, source, or configure must be supplied alongside data.
    templatestringThe Handlebars template the supplied documentation will be rendered into. Enables full control over the output.
    heading-depthnumberThe initial heading depth. For example, with a value of 2 the top-level markdown headings look like ## The heading.
    example-langstringSpecifies the default language used in @example blocks (for syntax highlighting). In GFM mode, each @example is wrapped in a fenced-code block. Example usage: js. Use none for no specific language. You can override this per-example using the @lang subtag (e.g., @example @lang hbs). Specifying @example @lang off disables code blocks for that example.
    pluginstring or Array<string>Use an installed package containing helper and/or partial overrides.
    helperstring or Array<string>Handlebars helper files to override or extend the default set.
    partialstring or Array<string>Handlebars partial files to override or extend the default set.
    name-formatstringFormat identifier names as code (i.e. wrap function/property/class etc names in backticks).
    no-gfmbooleanIf true, disables GitHub-Flavoured Markdown syntax. Useful if your markdown parser does not support GFM correctly.
    separatorsbooleanPut <hr> breaks between identifiers to improve readability.
    module-index-formatstringOptions: none, grouped, table, dl.
    global-index-formatstringOptions: none, grouped, table, dl.
    param-list-formatstringOptions: list or table (default). Use list if tables look crowded.
    property-list-formatstringOptions: list, table.
    member-index-formatstringOptions: grouped, list.
    clever-linksbooleanIf true, URL {@link} tags are rendered in plain text.
    monospace-linksbooleanIf true, all {@link} tags are rendered in monospace format. This is ignored if clever-links is set.
    EOLstringSpecify posix or win32 to force all line endings in the output.
    const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' })

  9. Configure JsdocOptions for the underlying JSDoc engine

    master

    When passing options to jsdoc-to-markdown, you can provide a configuration object that is processed by the JsdocOptions class. This class manages how options are passed to the underlying jsdoc-api.

    Key behaviors include:

    • Caching: By default, caching is enabled. To disable it, pass the no-cache option in your configuration object. The class will internally convert this to a cache boolean set to false.
    • Template handling: The template option is explicitly removed from the options object before being passed to jsdoc-api to prevent errors, as jsdoc-api expects the template option to be a specific filename rather than a general template configuration.

  11. Clear the jsdoc2md cache

    master
    By default, jsdoc2md caches results in the system's temporary directory to speed up subsequent runs with the same input. If you need to force a fresh generation or if the cache is behaving unexpectedly, use the clear() method to wipe both the jsdoc-api and dmd caches.

  12. Get JSDoc namepaths with JsdocToMarkdown.getNamepaths()

    master

    The getNamepaths() method returns an object containing arrays of JSDoc namepaths, categorized by their kind. This is useful for building navigation or indexes.

    Supported kinds include:

    • module, class, constructor, mixin, member, namespace, constant, function, event, typedef, external.