# doxdown

> jsDoc to MkDocs markdown generator

Latest version **2.0.1** (published 2017-03-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install doxdown
pnpm add doxdown
yarn add doxdown
bun add doxdown
```

Provides the command `doxdown`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2017-03-06 |
| First published | 2016-07-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Mike Geldard |
| Maintainers | lebowski89 |
| Keywords | jsDoc, MkDocs, markdown, generator |

## Links

- npm: https://www.npmjs.com/package/doxdown
- Repository: https://github.com/Degree53/doxdown
- Homepage: https://github.com/Degree53/doxdown#readme
- Issues: https://github.com/Degree53/doxdown/issues
- npm.io page: https://npm.io/package/doxdown

## Dependencies (6)

- [dox](https://npm.io/package/dox.md) ^0.8.1
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [rimraf](https://npm.io/package/rimraf.md) ^2.5.3
- [bluebird](https://npm.io/package/bluebird.md) ^3.4.1
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [cli-color](https://npm.io/package/cli-color.md) ^1.1.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2017-03-06
- 2.0.0 — 2016-08-09
- 1.0.3 — 2016-08-03
- 1.0.2 — 2016-08-03
- 1.0.1 — 2016-08-03
- 1.0.0 — 2016-07-27

## README

# doxdown

***doxdown*** is a jsDoc to [MkDocs](http://www.mkdocs.org/) markdown generator. It allows you to control your documentation on a comment by comment basis, choosing the page and document the comment belongs to. This is especially useful when you need to document an API separate to the rest of your codebase.

Running it on a directory with the default options will parse all nested JavaScript files and output a `./doxdown` folder. Inside will be a folder for each document with Markdown files and a `mkdocs.yml` file in the format expected by [MkDocs](http://www.mkdocs.org/). You can then run [MkDocs](http://www.mkdocs.org/) on any of those folders to build a site that you can deploy to a server.

## Installation

The easiest way to get ***doxdown*** is with NPM: `npm install doxdown --global`

## Usage / Options

Use the command `doxdown` with the following options to generate your docs:

Name | Alias | Default | Description
--- | :---: | --- | ---
ignore | i | `.git,node_modules` | comma-separated list of files/directories to ignore
out | o | `./doxdown` | relative path to the output directory
regex | r | `\.js$` | regex string for matching files in the source directory
src | s | `./` | relative path to the source directory

## Comment Format

***doxdown*** looks for jsDoc-style comments with a special `@docs` tag in the format `document [// page] // section` which describes where the comment belongs in which document. Use a jsDoc `@desc` to describe the function or event in the format `@name - description`. You can have any number of `@params` or `@data` tags and one `@returns` tag.

```javascript
/**
 * @docs Some Docs // Users & Accounts // User Helpers
 * @desc getUsernames - A description of getUsernames
 * @param {Object[]} users - An array of user objects
 * @param {String} users[].name - A user's name
 * @param {Number} limit - The max number to return
 * @returns {String[]} An array of usernames
 */

function getUsernames (users, limit) {
	
	const usernames = [];
	
	for (let i = 0; i < limit; i++) {
		usernames.push(users[i].name);
	}
	
	return usernames;
}

/**
 * @docs Tracking // Registration
 * @desc registration-complete - Fires when a user successfully completes registration.
 * @data {String} forename - The user's forename
 * @data {String} surname - The user's surname
 * @data {Date} dob - The user's date of birth
 * @data {Object} address - An object containing details of a user's address
 * @data {String} address.house - The house name/no. of the user's address
 * @data {String} address.postcode - The postcode of the user's address
 */

SomeTrackingAPI.trigger('registration-complete', {
	forename: "Sherlock",
	surname: "Holmes"
	dob: dateOfBirth,
	address: {
		house: "221B",
		postcode: "NW16XE"
	}
});

```

## TODO
- Replace `regex` option with glob pattern for matching files and directories.

---
_Source: https://npm.io/package/doxdown · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._