jsdoc-to-markdown
Advanced tools
Readme
Try the jsdoc2md v2 pre-release
jsdoc documented source code in, markdown format API documentation out.
write documented code:
/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}
run a command:
$ jsdoc2md example/src/protection.js
get markdown docs! (in github-flavored-markdown format by default)
<a name="protection"></a>
## protection(cloak, dagger) ⇒ <code>survival</code>
a quite wonderful function
| Param | Type | Description |
| ------ | ------------------- | ------------ |
| cloak | <code>object</code> | privacy gown |
| dagger | <code>object</code> | security |
this command achieves the same result:
$ jsdoc-parse example/function.js | dmd
.js or .html input files (parsing html is experimental - more)@fulfil, @reject, @hatredlevel etc.Some example output creating using jsdoc2md.
These projects insert jsdoc2md output into a readme template.
| Project | Notes |
|---|---|
| handbrake-js |
A module exposing two methods and an inner class. The API docs are inserted into this README template by this command: |
| command-line-args | Demonstrates documentation of ES2015 classes plus the @module, @typicalname, @throws and @alias tags. |
| array-tools | Very simple module exporting a collection of static methods. Demonstrates use of @category to group identifiers in the member-list. |
| jesucarr/tokenbucket | Demonstrates --param-list-format list and the documentation of Promises using the @fulfil and @reject tags. |
| ansi-escape-sequences | Demonstrates usage of @enum {type} (rendered in table format). |
You can see an example of how each jsdoc tag looks when rendered here.
To get an idea of the affects the various options have:
If you can't achieve what you need using the command-line tool you can write a custom script.
The default jsdoc2md output might not always suit you. You can supply your using own template using the template option. You can see the template used to generate this README here.
See the wiki for more great API examples. Feel free to add your own!
First, document your source code using correct jsdoc syntax then run it through jsdoc-to-markdown using one of the following methods (all tested on Mac OSX, Linux, Windows 8.1 and Windows XP):
To install the jsdoc2md command-line tool globally, run:
$ npm install -g jsdoc-to-markdown
Some typical use cases:
$ # dump everything you have into a single file
$ jsdoc2md "src/**/*.js" > api.md
$ # split into separate files
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md
$ # embed documentation into a template you made
$ jsdoc2md "src/**/*.js" --template readme.hbs > README.md
General rule: if your file expression contains ** yet recursion is failing, wrap the expression in quotes (e.g. "lib/**/*.js").
If wrapped in quotes, bash (or your shell) will not attempt file-name expansion on the expression. If you do not use quotes you will require bash version 4+ with globstar enabled for recursion to work.
npm run taskThis is the most lightweight way to add the task - no additional task-running software required. First:
$ npm install jsdoc-to-markdown --save-dev
Then, in the "scripts" section of package.json, add a docs task. For example:
{
"scripts": {
"docs": "jsdoc2md lib/*.js > api.md"
}
}
Now, project documentation is generated like so:
$ npm run docs
Issue reports and patches are encouraged. And the project would benefit from an additional maintainer..
Essentially, jsdoc2d connects the output of jsdoc-parse to the input of dmd. dmd uses the ddata helper library (also shared by dhtml) and stream-handlebars to generate the output.
Example
var jsdoc2md = require("jsdoc-to-markdown")
TransformStream ⏏Transforms jsdoc into markdown documentation.
Kind: Exported function
Params
DmdOptions | ParseOptions - the optionsExample
Two ways to use jsdoc2md. Either pass in filepaths (** glob matching supported) of javascript source files:
> jsdoc2md({ src: "lib/*.js" }).pipe(process.stdout)
or pipe in source code from another source:
> fs.createReadStream("lib/main.js").pipe(jsdoc2md()).pipe(process.stdout)
All dmd options and their defaults
Kind: inner class of dmd
stringnumberstringarrayarrayarraystringbooleanbooleanstringstringstringstringstringarraystringThe template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.
Kind: instance property of DmdOptions
Default: "{{>main}}"
Example
var fs = require("fs")
var dmd = require("../")
var template = "The description from my class: {{#class name='MyClass'}}{{description}}{{/class}}"
fs.createReadStream(__dirname + "/my-class.json")
.pipe(dmd({ template: template }))
.pipe(process.stdout)
outputs:
The description from my class: MyClass is full of wonder
the equivation operation using the command-line tool:
$ dmd --template template.hbs --src my-class.json
numberThe initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading".
Kind: instance property of DmdOptions
Default: 2
stringSpecifies the default language used in @example blocks (for syntax-highlighting purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: --example-lang js. Use the special value none for no specific language. While using this option, you can override the supplied language for any @example by specifying the @lang subtag, e.g @example @lang hbs. Specifying @example @lang off will disable code blocks for that example.
Kind: instance property of DmdOptions
Default: "js"
arrayUse an installed package containing helper and/or partial overrides
Kind: instance property of DmdOptions
arrayhandlebars helper files to override or extend the default set
Kind: instance property of DmdOptions
arrayhandlebars partial files to override or extend the default set
Kind: instance property of DmdOptions
stringFormat identifier names in the code style, (i.e. format using backticks or <code></code>)
Kind: instance property of DmdOptions
booleanBy default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
Kind: instance property of DmdOptions
booleanPut <hr> breaks between identifiers. Improves readability on bulky docs.
Kind: instance property of DmdOptions
Default: false
stringnone, grouped, table, dl
Kind: instance property of DmdOptions
Default: "dl"
stringnone, grouped, table, dl
Kind: instance property of DmdOptions
Default: "dl"
stringTwo options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.
Kind: instance property of DmdOptions
Default: "table"
stringlist, table
Kind: instance property of DmdOptions
Default: "table"
stringgrouped, list
Kind: instance property of DmdOptions
Default: "grouped"
arraya list of fields to group member indexes by
Kind: instance property of DmdOptions
Default: ["scope","category"]
All options for jsdoc-parse, including defaults
Kind: inner class of jsdocParse
string | Array.<string>A list of javascript source files (or glob expressions) to parse for documentation. If this option is not set jsdoc-parse will wait for source code on stdin (i.e. cat *.js | jsdoc-parse <options>).
Kind: instance property of ParseOptions
Example
var parse = require("jsdoc-parse")
var fs = require("fs")
// either supply one or more file names
parse({ src: "example.js" }).pipe(process.stdout)
// or pipe in source code
fs.createReadStream("example.js").parse().pipe(process.stdout)
booleanInclude identifier documentation marked as @private in the output
Kind: instance property of ParseOptions
Default: false
booleanPrint a few stats about the doclets parsed
Kind: instance property of ParseOptions
booleanEnable experimental parsing of .html files.
Kind: instance property of ParseOptions
Default: false
booleanPath to a jsdoc configuration file, passed directly to jsdoc -c.
Kind: instance property of ParseOptions
arraySort by one of more fields, e.g. --sort-by kind category. Pass the special value none to remove the default sort order.
Kind: instance property of ParseOptions
Default: ["scope","category","kind","order"]
© 2014-16 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.
FAQs
Generates markdown API documentation from jsdoc annotated source code
The npm package jsdoc-to-markdown receives a total of 114,829 weekly downloads. As such, jsdoc-to-markdown popularity was classified as popular.
We found that jsdoc-to-markdown demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.